Application structure
Organize browser/server targets, shared contracts, native configuration, and retained Framework artifacts.
Keep native targets explicit
Start from the layout of the Recipe you adopted. Smoothie Starter separates browser and server entrypoints while keeping shared contracts safe to import from either side. This is a source convention, not a required Framework application graph or global App object.
my-product/
package.json
bun.lock
smoothie.toml
vite.config.ts
shared/
contracts.ts
targets/
web/src/
main.tsx
router.tsx
styles.css
server/
endpoints.ts
app.ts
main.ts
cloudflare.ts
vendor/smoothie/
application.json
recipe.json
releases/Enforce import boundaries
Keep feature code together when it helps navigation, but do not import server modules into browser code. Importing a shared contract must not start a listener, Worker, or model request. Let each native entrypoint start resources and arrange cleanup for what it owns.
Keep release files with the project
The project-local acquisition workflow stores downloaded source separately from the packages your application installs:
.smoothie/framework/
selected.json # commit: release to acquire
releases/<short-release>/ # ignored download cache
source/ # Framework source, Recipes and Figma library
bundle/ # verified package bundle
vendor/smoothie/
application.json # commit: installed package selection
recipe.json # commit: original Starter identity
releases/<short-release>/ # commit: selected archives and release recordsCommit selected.json, vendor/smoothie/, package.json and bun.lock to your private repository. Keep only /.smoothie/framework/releases/ ignored; ignoring all of .smoothie/ would hide the selected version. The source/Figma cache can be deleted without breaking package installation from vendor/smoothie/.
Short folder names are for readability. Release records retain full revisions and hashes, and the CLI checks those identities before reusing files. Package selections from the same release share one vendor folder; there is no additional selection directory. Older layouts remain readable and migrate when you explicitly run framework use.
Acquired source and installed packages can differ until you run framework use. Check selected.json for the next source selection and application.json for what the app uses. Make Framework source customizations in a separate copy; files in the download cache are verified release files.
Separate identity from execution
smoothie.toml identifies the project and its declared contracts. package.json and bun.lock own dependencies and scripts; native host configuration owns deployment settings. Do not add provider credentials, task graphs, or runtime profiles to the project manifest. See Configuration and environment.
Add another target only for a real independently executed boundary. A future non-TypeScript target should keep its native layout and communicate through explicit contracts; its existence does not imply another supported SDK in this release.