Skip to content
Browse documentation
start here

Add Smoothie to an existing project

Add prepared Framework packages to a single Bun project without replacing product source or native tooling.

Requirements

You can add Framework packages to an existing project without copying a Recipe. Your renderer, router, HTTP host, and product source stay as they are. This flow currently supports a single Bun project whose root package.json pins an exact Bun version, with an optional text bun.lock. Bun or npm workspaces, the binary bun.lockb format, and other package managers are not supported. Work on a branch so you can review every dependency change.

Download and verify a release inside your project. The example below assumes your project is my-product/ and you have selected its Framework release. Before you start, make sure package.json contains an exact packageManager pin:

json
"packageManager": "bun@1.4.2"

Add Framework packages

bash
smoothie framework use \
  --package @smoothie-framework/service --dry-run --format json

This example adds the portable Service package and the Framework packages it depends on. Repeat --package for each Framework package your code imports directly, using names present in your release. Review the planned package.json changes, then copy data.planId into the command below and run it from the same directory with the same arguments.

bash
smoothie framework use \
  --package @smoothie-framework/service --expect-plan <data.planId>
bun install --ignore-scripts

The apply step stores the selected archives under vendor/smoothie/ and points package.json at them: each package you name is added to dependencies, and every package in the closure gets an overrides entry. It does not copy Recipe source or add a runtime. Your other dependency values are preserved, although package.json formatting may change. Installation is a separate step; review the package.json and bun.lock diffs before committing.

For a separately stored release, add /path/to/release/bundle and --source /path/to/release/source to both use commands. Keep the same --package selection and review the plan before applying.

Add smoothie.toml

Adding packages does not create smoothie.toml, which the project commands need. If your project has none, create one at its root as shown below. Do not overwrite an existing file. If your project already belongs to a Smoothie workspace, that is, a parent smoothie.toml declares it as a member, keep that membership instead.

toml
schema = 1

[project]
name = "my-product"
sdk = "typescript"
bash
smoothie project context --format json
smoothie project check
smoothie project verify

These commands read the retained release record, metadata, and supported package.json scripts. To run checks, add --task and --run, or use your own tools. smoothie.toml does not configure providers, deployment, dependencies, or builds. You do not need project adopt for this path; it registers members of a Smoothie workspace and does not install packages.

Use the packages

Read each selected package's README, stored under vendor/smoothie/, before adding imports and host bindings. Installing Service does not start a server; add the matching host adapter, such as Elysia, when you need one. For UI-only adoption, see the whisk/ui documentation. Your application still owns credentials, authorization, side effects, tests, and shutdown.