This is the canonical "build something real" walkthrough for a new Quark project.
It assumes the minimal scaffold is present (apps/web, packages/db, packages/config) and treats optional packages like ui, jobs, admin, and cms as add-ons rather than prerequisites.
Add a simple Task feature that proves the full workflow:
apps/webOpen packages/db/prisma/schema.prisma and add a domain model.
Use the Quark defaults:
id String @id @default(cuid())createdAt DateTime @default(now())updatedAt DateTime @updatedAtIf the data belongs to a user, relate it to User explicitly.
pnpm db:generate
pnpm db:migrateUse db:migrate for real schema changes. Reserve db:push for throwaway local experiments.
Open packages/db/src/queries.js and add a small query surface for the new model.
Follow the existing pattern:
prisma.task.* directly inside pages or actionsTypical first helpers:
findAllfindByIdcreateupdatedeleteCreate a route in apps/web/src/app/ that uses the query helpers.
For example:
apps/web/src/app/tasks/page.js for the read pathapps/web/src/app/tasks/_actions/create-task.js for a mutation via Server ActionDefault to the standard Quark pattern:
AppError / ValidationError for failurescreateLogger() instead of console.logIf your project includes ui, build the page with components from @yourapp/ui.
Add one test that proves the new feature works in the layer you changed first.
Good first choices:
packages/db/src/queries.jsDo not start with a huge end-to-end test if a smaller test will prove the behavior.
Once the first vertical slice works, add optional Quark features when they help:
| Feature | When to add it |
|---|---|
jobs | The feature needs async work like email, imports, or cleanup |
pwa | You want installability and offline caching |
mobile | You want a native Expo app alongside the web app (post-creation only) |
ui is already scaffolded, so you do not need to add it.
Add optional features later with:
npx quark add <feature>For admin dashboards, CMS, CRM, bookings, or AI features, there is no package to install. Load the relevant skill and let your AI tool build it: see the skill index in <harness>/skills/ (default .opencode/skills/).
schema.prismapnpm db:generate runpnpm db:migrate runWhen that is done, you are no longer learning the scaffold - you are building product code.