Skip to content

Start from the template

The starter is a to-do list with sign-in: people create an account with their email and a password, then keep their own list. Get it with the CLI:

npm create flatstack@latest my-todos
cd my-todos
npm install
npx flatstack login
npx flatstack launch

The first line writes the starter; launch creates the project, links the folder and deploys it, and prints its URL (Deploy it has the details). Instead of npm create, you can run the same thing through the CLI directly, npx @flatstackdev/cli@latest init my-todos. This writes the starter into my-todos/ and names its package after the folder. The template comes with the CLI, so nothing else is downloaded. Its source is templates/starter in the Flatstack repository.

Building with Next.js, Astro or React Router? npx @flatstackdev/cli@latest init my-app --template next (or astro, react-router) writes a starter for that framework instead, with its pages rendered in your project’s Worker: see Server-rendered apps.

The project’s package.json asks for @flatstackdev/server, the SDK its code imports, and @flatstackdev/cli as a dev dependency. After npm install, npx flatstack … in the folder runs that copy of the CLI; npm run dev and npm run deploy do the same.

What it shows

  • An owner-only table in flatstack/schema.ts, and the migration flatstack db diff wrote for it.
  • Four functions in flatstack/functions/todos.ts, each with an input schema, auth: "required" and ctx.db.asUser(), so one user can never read or change another’s rows. They pass the security scan with no findings.
  • A sign-up hook in flatstack/auth.ts. Email and password sign-in is on by default.
  • A page in public/ that calls the functions at /fn/<name> and sign-in at /auth/* with plain fetch, styled with Flatstack’s design tokens.

Run it locally

In the new folder:

npm install
npx flatstack dev

Open http://127.0.0.1:8788, create an account and add a to-do. flatstack dev serves the page from public/, your functions and sign-in, with a local database in .flatstack/dev/. Emails sign-in would send, such as the verification email, aren’t sent: http://127.0.0.1:8788/auth/fs/dev/outbox?to=<email> lists them. See Local development.

Deploy it

npx flatstack login
npx flatstack launch

launch creates a project named after the folder, links the folder to it in .flatstack/project.json (commit that file to share the link) and deploys. Run it again after a change and it only deploys; npx flatstack deploy does the same. To choose the name or subdomain, pass --name or --slug the first time. See Launching.

The deploy uploads the page in public/ with your functions, after the security scan has checked it for leaked secrets, and your app’s address serves it. Later deploys send only the files that changed (how it’s served). See the CLI and Deploying for what each step does.

As Markdown: apps/starter.md