Getting Started with the Boilerplate

The fastest way to start a FuryStack project. Clone a ready-made template with authentication, REST API, and a Shades frontend — all wired up.

The Boilerplate repository is a GitHub template you can use to create your own repo in seconds. It is a Yarn workspaces monorepo with three packages: common, service, and frontend.

Quick start

Open the boilerplate repo and click Use this template to create your own repository.

Clone your new repo and install dependencies:

git clone https://github.com/your-user/your-repo.git
cd your-repo
yarn install

Build all workspaces:
```
yarn build
```
Start the backend and frontend (in separate terminals):
```
yarn start:service
yarn start:frontend
```
Open http://localhost:8080/ in your browser.

Project structure

The monorepo is managed with Yarn 4 workspaces. Every package uses ESM ("type": "module") and TypeScript with project references (tsc -b).

common

Shared models and type-safe REST API definitions. Both the service and the frontend depend on this package via "common": "workspace:^".

The API contract is defined as a TypeScript interface that extends RestApi from @furystack/rest:

import type { RestApi } from '@furystack/rest'
import type { User } from './models/index.js'

export interface BoilerplateApi extends RestApi {
  GET: {
    '/isAuthenticated': { result: { isAuthenticated: boolean } }
    '/currentUser': { result: User }
    '/testQuery': { query: { param1: string }; result: { param1Value: string } }
  }
  POST: {
    '/login': { result: User; body: { username: string; password: string } }
    '/logout': { result: unknown }
  }
}

This single interface drives both the server routing and the client’s typed fetch calls, giving you end-to-end type safety.

service

The Node.js backend, built entirely on FuryStack packages:

@furystack/core — InMemoryStore, addStore
@furystack/inject — dependency injection via Injector
@furystack/repository — data sets with authorization hooks
@furystack/rest-service — useRestService to spin up an HTTP server from the API type
@furystack/auth-jwt — JWT login / logout / refresh
@furystack/security — password hashing and policies
@furystack/filesystem-store — persist entities to JSON files
@furystack/logging — structured logging

The entry point wires everything together:

import { injector } from './root-injector.js'
import { attachShutdownHandler } from './shutdown-handler.js'
import { setupStore } from './setup-store.js'
import { setupRestApi } from './setup-rest-api.js'

void attachShutdownHandler(injector)
setupStore(injector)

setupRestApi(injector).catch((err) => {
  console.error(err)
  process.exit(1)
})

frontend

A single-page app built with Shades, FuryStack’s own JSX-based UI library. It is bundled with Vite and includes:

A basic layout with header, body, and routing
Login / logout using @furystack/auth-jwt
Type-safe API calls via @furystack/rest-client-fetch
Theming with @furystack/shades-common-components

Tooling

Linting: ESLint with @furystack/eslint-plugin + Prettier
Unit tests: Vitest — run with yarn test
E2E tests: Playwright — run with yarn test:e2e
Seed data: yarn seed creates a test user for development
Git hooks: Husky + lint-staged for pre-commit linting and formatting

What’s next?

Now that your project is running, explore the codebase and start adding your own models, endpoints, and pages. For deeper understanding of individual packages, check out the Getting Started hub for guided learning paths.