Quickstarts

Common flows (feature work, PR testing, server changes) using stacks + worktrees.

This page is the “copy/paste” companion to /docs/hstack/development.

If you’re new, read /docs/hstack/setup and /docs/hstack/worktrees-and-forks first.

1) Typical feature work (recommended)

Create a worktree based on upstream (clean PR history):

hstack wt new my-feature --from=upstream --use

Create an isolated stack and pin it to the active worktree:

hstack stack new exp1
hstack stack wt exp1 -- use active

Run the stack in dev mode:

hstack tui stack dev exp1

If you can’t use the TUI (non-interactive terminals / CI), run:

hstack stack dev exp1

Push the branch to your fork:

hstack wt push active --remote=origin

If you’re working directly on the dev branch (common for maintainers):

hstack stack new dev
hstack stack wt dev -- use dev
hstack tui stack dev dev
# (optional) mobile dev-client + QR:
hstack tui stack dev dev --mobile

Create a full-server stack:

hstack stack new full1 --server=happier-server

Then run dev:

hstack tui stack dev full1

Notes:

This uses Docker-managed Postgres/Redis/Minio for the stack.
If you don’t want Docker-managed infra, configure DATABASE_URL/REDIS_URL/S3_* in the stack env file and re-run.

Create a PR worktree:

hstack wt pr 123 --use

Create a PR stack that pins to it:

hstack stack pr pr123 --repo=123 --dev

If you have a dev-auth seed stack, you can seed and link/copy auth:

hstack stack pr pr123 --repo=123 --dev --seed-auth --copy-auth-from=dev-auth --link-auth

If you have changes that live in a legacy split-repo layout (old UI/CLI/server repos), use:

For quick checks against your current checkout (non-stack-scoped):

hstack typecheck all
hstack lint all
hstack test all

For stack-scoped validation (recommended when debugging runtime issues):

hstack stack typecheck exp1 all
hstack stack lint exp1 all
hstack stack test exp1 all