Skip to content
Browse documentation
start here

Create your first application

Create Smoothie Starter from a verified release, run selected checks, and open a working web application.

Prerequisites

This tutorial creates Smoothie Starter: a client-rendered Octane interface, a typed Service contract, and an Elysia server. You need the Smoothie CLI, Bun 1.4.2, Node 24, and the verified source/ and bundle/ from Obtain a Framework release. No database or model credentials are required. Run the commands from the project directory where you acquired the release.

Run bun --version first: the CLI reports a Bun version that differs from the project's pin but does not install Bun for you.

Create in your project

After acquiring a release, run from the directory containing .smoothie/framework/selected.json. Review the dry-run result, then copy data.planId into the apply command:

smoothie recipe create smoothie-starter --dry-run --format json
smoothie recipe create smoothie-starter --expect-plan <data.planId>

Replace data.planId with the value from the dry run. The CLI uses your selected release and creates the application in the current directory. It preserves .smoothie/, .git/ and .gitignore and refuses a destination containing other files. Pass --project /path/to/my-product to work from another directory.

Continue with dependency installation below. Commit .smoothie/framework/selected.json alongside the application and vendor files; leave the downloaded .smoothie/framework/releases/ cache ignored.

Install application dependencies

bash
bun install --ignore-scripts

Bun installs the Framework archives stored in the application and resolves third-party dependencies from public registries. No SDK build or private repository login is needed. Install scripts are disabled; review any dependency that genuinely needs one separately. Commit the generated bun.lock and vendor/smoothie/ to your private repository, and use bun install --frozen-lockfile --ignore-scripts for later unchanged installs.

Inspect and check the application

If your Starter includes a check script, run bun run check for formatting, lint and TypeScript checks before the tests below. See code checks for the individual commands.

bash
smoothie project context --format json
smoothie project check
smoothie project verify
smoothie project verify --task typecheck --task test --task build --run

The first three commands only read files. Context reports the project and the release it retains; expect a retained_archives_unverified warning, because context checks metadata consistency rather than archive bytes. To recheck the archives, run smoothie framework verify on the releasePath recorded in vendor/smoothie/application.json. Check validates metadata and contracts. Verify without --run lists the tasks it found.

The last command runs the typecheck, test, and build scripts and should report each as passed. Project scripts are your application's code: the CLI runs them without a sandbox, and a passing script can still skip tests internally. Investigate any blocked or failed result before continuing.

Run the application

bash
bun run start

The server prints Smoothie starter listening on http://127.0.0.1:42741. Open http://127.0.0.1:42741 and select Check server: the status should change to smoothie-starter: ok. Open About, then refresh the page to confirm that deep links work. Stop the server with Ctrl-C.

bun run start serves the last build. For live editing, run the development servers instead and open http://127.0.0.1:42740; the browser reloads on change and the API stays on port 42741. The application owns these processes; the CLI does not provide a development runtime.

bash
bun run dev
Optional browser tests

Stop any running server first: the browser suite starts its own server on port 42741 and fails if the port is in use. Then download the project's Chromium and run the suite with the commands below. On Linux, Playwright names any missing system libraries; install them before retrying.

bash
./node_modules/.bin/playwright install chromium
smoothie project verify --task test:e2e --run

Application files

targets/web/src/Browser entry point, router, interface, and application shell CSS.
shared/contracts.tsService request and response contracts, safe to import from browser and server.
targets/server/Endpoint behavior, HTTP hosts, and server process lifetime. Keep secrets here.
smoothie.tomlProject name, SDK, and declared contracts; not a build or dependency graph.
package.json and bun.lockNative scripts, dependencies, and the resolved dependency versions.
vendor/smoothie/Retained release record, prepared package archives, notices, and Recipe baseline.

Edit the copied source as your product; package updates never overwrite it. The project is still named smoothie-starter in smoothie.toml and package.json, so rename it there. This Starter has no authentication, persistence, Agent execution, or SSR; add those capabilities deliberately.

Use separate release folders

If your release is stored outside the project, use explicit paths instead. Run these commands from the parent directory containing release-download/ and the new my-product/ destination. After creation, run cd my-product and continue with dependency installation.

bash
smoothie recipe create smoothie-starter ./my-product \
  --from ./release-download/source --bundle ./release-download/bundle \
  --dry-run --format json

The dry run verifies the inputs and returns a plan without writing anything. Review the destination, Recipe, package closure, and install choice in the result. Then copy data.planId, a 64-character hash, into the command below. Run it from the same directory with the same arguments: the plan records absolute paths, so a different directory or input produces a different plan and is refused.

bash
smoothie recipe create smoothie-starter ./my-product \
  --from ./release-download/source --bundle ./release-download/bundle \
  --expect-plan <data.planId>

Creation writes my-product/ with the Starter source, the prepared package archives it needs, and an adoption record. It contains only this Starter, not the SDK workspace or other Starters, and dependencies are not installed yet. An existing destination is never replaced. If creation is interrupted, keep the .smoothie-create-* directory it reports beside my-product/ for diagnosis, then retry with a fresh dry run.

Next steps

To work with an AI coding assistant, continue with Develop with a coding agent. For interface work, see whisk/ui. Read the application's README before adding another target or deploying: a successful local run does not qualify production security or hosting.