CoreModule Boundaries

Module Boundaries Reference

Notation splits one TypeScript project into an infrastructure bundle for Node and isolated runtime bundles for each deployed function. Static boundary checks keep deploy-time SDKs out of runtime bundles and runtime-only platform APIs out of deploy code.

Import contract

Every project file receives a module kind from files in notation.config.ts (infra, runtime, shared, or unmatched). Type-only imports and exports (import type, export type, and inline type specifiers) are erased before bundling and are permitted across every boundary.

Infra rules

Infra modules run only in Node during plan, deploy, and destroy:

RuleBehavior
Runtime declarationsInfra modules can import declaration bindings from runtime modules
Runtime helpersImporting non-declaration values from runtime modules fails the build
Platform importsStatic imports of runtime-only platform modules fail in deploy code

For example, an infra module can import export const lambda = $lambda(...) from a runtime module, while static cloudflare:* imports fail the build. Dynamic import() calls remain intact and only fail if executed at deploy time.

Runtime rules

Runtime modules participate in both builds:

BuildBehavior
Infra buildKeeps declarations and their dependencies while stubbing runtime-only options
Runtime buildKeeps runtime and shared declaration options and bundles one ESM entry file
Infra code leakageFails the build if a runtime bundle retains infra code or package builder calls

In the infra build, runtime-only options such as handler or entrypoint become throwing stubs, and non-declaration runtime modules strip everything except exports imported by deploy code. The runtime build bundles with codeSplitting: false and prints the import chain if any infra module or @resource/@declaration call leaks in.

Shared rules

Shared modules run unmodified in both the infra bundle and every runtime bundle that imports them. Compilation fails when a shared module breaks any of these rules:

RuleForbidden pattern
DeclarationsCalling a @declaration function such as $lambda, $worker, or $durableObject
Resource buildersImporting or re-exporting a @resource function directly, via namespace, or via export *
Boundary importsValue-importing any infra or runtime module directly or transitively

Unmatched files

Project script files that match none of infra, runtime, or shared receive no module kind:

RuleBehavior
Auto-discoveryUnmatched files are not scanned for runtime declaration roots
Explicit importsEither build can import an unmatched file as plain code
Top-level resourcesRuntime bundles fail if they retain top-level @resource calls from an unmatched file

Files in ignored directories or nested packages are excluded entirely. If a retained unmatched file or package triggers a top-level @resource error, add the file to files.infra or set "sideEffects": false on the nearest package.json.

Declaration placement

Static AST analysis enforces strict placement rules on @declaration calls ($lambda, $worker, $durableObject):

RuleRequirement
Module kindMust reside in a runtime module, never infra or shared
CardinalityAt most one declaration per runtime module
Top-level bindingMust initialize a single-declarator top-level const
Options shapeMust take one plain object literal argument
Required entryModule must export the entry name required by the declaration
Entry class orderClass named in entryOption must be declared earlier and exported
Reserved namesModule cannot declare __notation_declaredIn or __notation_unnamed

Calls inside a locally defined @declaration wrapper function do not count toward the one-per-module limit. The top-level const may be exported and wrapped in parentheses or TypeScript expressions such as satisfies. The options object cannot contain spread elements, computed property keys, or getters/setters. When a declaration sets entry (such as handler on $lambda or default on $worker), that export is required; when it sets entryOption (such as entrypoint on $worker), the value must be an identifier naming a class declared before the declaration in the same module and exported as entry – imported or re-exported classes are rejected.

Place each declaration at the top level of its runtime module with a plain object literal:

runtime/orders.ts
export const lambda = $lambda({
  id: "orders",
  event: () => sqs.bind(orderQueue),
});

Runtime thunk constraints

Declaration options that supply runtime configuration and references to infra resources must stay statically analyzable:

ConstraintRequirement
Object-literal thunksEach keys option must be a function returning one object literal
Direct resource expressionsKept infra resource references must be passed directly, not aliased
Object-literal resource configResources with runtime options must pass an object literal in infra
Direct runtime importsCopied runtime options must be direct named or default imports
Declaration output readsRuntime code cannot read outputs listed in @declaration outputs:

keys options (such as env on $lambda and bindings on $worker) must be arrow functions or function expressions returning a single object literal (() => ({ ... }) or () => { return { ... }; }) with no spread elements, computed keys, method shorthand, or accessors. Kept infra resource expressions (such as sqs.bind(orderQueue) or bindings: () => ({ ORDERS_CACHE: ordersCache })) must be passed directly as an imported identifier, object-literal member, or namespace member rather than a local const or helper return value. When a @resource specifies runtime options (such as schema on queue()), its infra call must pass an object literal with no spread hiding that option, and each copied value must be a direct named or default import from a shared module or compatible non-infra file rather than a namespace member or inline expression. Static reads of deploy-time outputs (such as worker.url on $worker) are rejected outside stripped or keys options.

Platform conditions

Runtime builds configure module resolution per target platform:

  • node ($lambda) – Resolves package exports with conditionNames: ["notation-runtime", "node", "import", "default"].
  • workerd ($worker, $durableObject) – Resolves with conditionNames: ["notation-runtime", "workerd", "worker", "browser", "import", "default"] and mainFields: ["browser", "module", "main"], marks cloudflare:* imports external, normalizes Node built-in imports (fs and node:fs) to external node:<name> modules, and replaces process.env.NODE_ENV (default "production").

Helpers that only function inside a runtime bundle (such as lambda.env()) rely on the "notation-runtime" export condition. Running unit tests against runtime modules outside notation compile requires passing --conditions=notation-runtime to the test runner.

Worker export checks

Because workerd fails to start a Worker module that exports primitives or module namespace objects, Notation checks all non-default, non-declaration exports of a Worker module statically:

  • Primitive const exports – Rejects top-level export const declarations initialized to primitive literals (strings, numbers, booleans, null, excluding regex literals), template literals, unary or binary expressions, or undefined.
  • Namespace re-exports – Rejects export * as ns from "...".

Exporting functions, classes, plain objects, let/var bindings, or type-only exports passes the check. Move shared constants to shared/ or pass them through bindings().

Compile checks

Running notation compile executes both build passes and verifies every static boundary rule without evaluating infrastructure or requiring cloud credentials:

CheckScope
Config globsValidates notation.config.ts and rejects overlapping module globs
Declaration ASTEnforces single declaration, object-literal options, and entry exports
Shared isolationRejects declarations, @resource imports, and infra or runtime imports in shared
Infra isolationRejects non-declaration runtime imports and kept static cloudflare:* imports
Runtime isolationStubs infra resource references and rejects leaked infra code or output reads
Worker exportsRejects primitive const exports and export * as ns in workerd entries

notation compile bundles TypeScript via Rolldown without running tsc typechecking. Run tsc --noEmit separately in CI or local scripts to verify TypeScript types. See Module Analysis for compiler internals.