Workspace

HOW TO USE FULLSTACK TOOLKIT

From a template to your own live product

Create an independent codebase, build a business workflow, pass the checks, then publish a version. These are developer actions performed in your terminal and repository.

The board is a working demo. Planned / In progress / Completed only save card status; they do not generate code, run CI or deploy a website.

  1. Create a real project

    Install Git and GitHub CLI, sign in, then use the template to create an independent repository and clone it. Replace YOUR_ACCOUNT and my-product with your own names. The board below creates records, not repositories.

    gh auth login
gh repo create YOUR_ACCOUNT/my-product --template chenhynju/fullstack-toolkit --private --clone
cd my-product
node scripts/init-project.mjs my-product

    The initializer changes the root package name and README titles and creates .env if absent. Update the visible branding separately. Keep @repo/* names unless updating all workspace references.

  2. Run locally and develop one complete workflow

    Install Node 22.14+ and the pinned pnpm 11.7.0. Use a new branch and a private development environment. For a booking app, first finish selecting a slot → booking → viewing/cancelling it, including failure paths.

    corepack enable
git switch -c feat/first-business-flow
pnpm install --frozen-lockfile
pnpm db:migrate
pnpm dev

    Open http://localhost:3000; the API uses 3001. Check that ports are free. Reuse authentication, error handling and i18n, then add your own domain rules. Every product needs its own database and environment.

    Where your business code belongs

    apps/web
    Pages, forms and interactions
    apps/api
    Validation, business rules and server-side permissions
    packages/db
    Data model and versioned migrations
    packages/types
    Shared frontend/backend contracts
    apps/web/lib/messages.ts
    English/Chinese interface copy

  3. Make quality a release gate

    Run these from the project root. Fix every failure before merging. Add tests for real business behavior: invalid input, permissions, isolation and a browser journey, beyond a successful build or HTTP 200.

    pnpm format:check
pnpm lint
pnpm typecheck
pnpm test
pnpm build
pnpm size-check
pnpm e2e

    Use a disposable database for browser tests: they create accounts and data. An administrator journey needs explicitly configured test credentials. A skipped test is not a pass. GitHub required checks must be enabled separately.

  4. Push to GitHub and review a pull request

    Review your diff, commit a focused change and open a PR. Check Actions logs and test reports; require the quality-gate and e2e checks before merging into main.

    git diff
git status
git add apps/web apps/api packages/db packages/types
git commit -m "feat(booking): add first booking workflow"
git push --set-upstream origin feat/first-business-flow
gh pr create --base main --fill

    Stage only reviewed paths; add reviewed configuration/docs changes when needed. Never commit .env, credentials, databases or uploads. Configure branch protection, GitHub Environments and deployment secrets for each new repository; template files do not configure those settings.

  5. Deploy an independent product

    After tests pass, package the source and upload it to the new product’s own server directory. Configure an unused domain, ports and a private runtime.env. The example below is a Linux server command run from that uploaded project root.

    python scripts/package_release.py .local/my-product-v1.tgz

# On the server, from the uploaded project root:
docker compose --project-name my-product --env-file /opt/my-product/shared/runtime.env -f docker/docker-compose.yml up -d --build

    Set APP_ORIGIN=https://my-product.example.com, unused WEB_PORT/API_PORT and a unique RELEASE_TAG=my-product-v1 in the private server file. Compose creates a separate project volume. Point DNS to the host, configure a dedicated Caddy HTTPS site and verify /api/health, /api/ready and the actual business flow. Replace example.com with your own domain. Protect runtime.env with chmod 600 and keep it out of Git.

  6. Release updates and recover safely

    Release with a new immutable version tag. Before database migrations, create and verify a consistent backup. Keep the previous images and source, run public HTTPS acceptance and check other services after switching.

    Use the previous images only with a compatible schema; otherwise restore the matching backup. Never run docker compose down -v on a live product. scripts/release.sh and the existing Deploy workflow target this toolkit installation: adapt host paths, ports, image names and secrets before using them for another product. Vercel/GHCR flows remain separate work, not actions triggered by a board status.

Open the GitHub template ↗Full operation manualDeployment and recovery runbook ↗

The demo workspace follows below. Use the steps above to build an actual new product.

Opening your workspace…

User manual