Skip to content
Browse documentation
guides

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.

text
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

shared/Transport-safe contracts and pure shared code. No database handles, provider credentials, or executable host entrypoints.
targets/web/Browser root, native router, interface, and browser-owned cleanup.
targets/server/Server-only adapters, authorization, endpoint behavior, and native host lifetime.
Root tool configurationNative build/test/style configuration. Root placement does not make a module safe to import into the browser.
vendor/smoothie/Immutable release archives, notices and control records. Do not edit package bytes in place.

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 records

Commit 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.