Skip to content
Browse documentation
guides

Customize Framework source

Keep SDK changes in a private source checkout and verify explicitly identified custom package archives before installation.

Change Framework source separately from your app

Edit copied Recipe source directly in your application. To change an SDK implementation, keep a separate private working copy of the entitled source matching your installed release. Preserve the original verified source and bundle as the baseline; modifying hash-listed source in place invalidates its original verification records.

Record the baseline and your changes in your own private Git history. A fork can help maintain upstream changes while access is available, but your retained source and build must not depend on continued repository access. Review license and third-party notice obligations before sharing any copy. Repository access does not automatically authorize publishing proprietary source or contributing changes upstream.

Build, test, and pack with native tools

Use the source checkout's pinned toolchain and package scripts. Change only the required package and its affected dependency/consumer closure, assign distinct replacement versions, and keep internal dependency requirements coherent. Test the resulting archives in an independent application, not only through workspace aliases. The app should continue to consume prepared archives instead of building the SDK on every install.

There is no Smoothie CLI command that compiles custom SDK source. project build prepares an application deployment payload; it is not a Framework package builder. Building and packing alone also do not create a CLI-compatible customer-build inventory.

Keep custom provenance distinct

text
custom-bundle/
  framework-packages.json   # unchanged baseline inventory
  packages/                # unchanged original archives
  custom-packages/          # distinctly versioned replacement archives
  customer-build.json      # custom identity and exact replacement records
  ...                      # retained baseline metadata and notices
schema and idSchema 1 and a distinct lowercase-kebab customer-build identity.
baselineInventorySha256 and releaseThe unchanged original inventory hash and baseline release identity.
sourceThe private source commit revision and tree ids used for the build.
toolchainExact observed Bun, Node, and TypeScript versions.
replacementsKnown baseline package names, distinct versions, commercial license identity, archive paths/byte counts/SHA-256, dependency and peer maps, and optional-peer declarations.

This is an advanced, manually prepared record, not an automatically generated CLI output. Read the Customer builds section of docs/specs/cli/framework-control.md in your retained source or release-local context for the complete record contract. All unchanged baseline metadata/notices and the selected dependency closure must remain available. Never rewrite an official inventory or swap bytes behind an existing file dependency to make your changes look official.

Verify and select the customized packages

bash
smoothie framework verify ../custom-bundle
smoothie framework use ../custom-bundle --project . --dry-run --format json
smoothie framework use ../custom-bundle --project . --expect-plan <data.planId>
bun install --ignore-scripts
smoothie project verify --task typecheck --task test --task build --run

Replace data.planId only after reviewing the plan. This example uses an already managed application's recorded roots; every replacement must belong to that closure. The CLI validates effective package requirements and archive integrity, but declared source commit and toolchain fields are not a verified Git-history or reproducibility proof. Results and retained paths identify the custom build explicitly.

To return to official packages, select the retained original bundle using the update and rollback guide. Port custom source changes onto a newer upstream baseline in the independent source checkout, rebuild, and qualify a new custom inventory. No automatic source merge is performed.