Appearance
Performance
Twill compiles to ordinary JavaScript. Its performance depends on the emitted code, compilation workflow and optional libraries you use. This guide explains where costs arise and how to evaluate them in your application.
The behavior described here applies to the 0.4.1 toolchain. Measurements below retain their original version and environment; they are examples of particular workloads, not new measurements of every 0.4.1 application.
| What you use | Where costs arise | What to inspect |
|---|---|---|
| Trailing closures and guards | Native arrows, branches and destructuring | Generated JavaScript and your application's hot paths |
defer, switch and component expressions | The selected lowering can add callbacks, stacks, arrays or an expression wrapper | Allocation, output size and equivalent native control flow |
| Compiler and editor | Transformation, TypeScript checking, configuration and source mapping | Full builds and feedback after real edits |
| Direct script execution | Node startup, loading and source compilation; validated hits skip compiler initialization | First launch, cache misses and cache hits separately |
| Optional shell SDK | Child-process coordination, bounded capture, decoding and teardown | Equivalent subprocess work with the same I/O policy |
Generated JavaScript and runtime cost
Native paths stay native
Ordinary trailing closures become arrow functions. Guards become native branches; nullish bindings use strict null/undefined checks and native destructuring. These constructs introduce no language runtime library. Checked types are erased before execution.
Single-expression component children become direct JSX values. Parameterized render props remain callbacks. Framework rendering, scheduling and state management retain the costs of React, Vue or the framework you choose.
Some forms do additional work
Eligible direct synchronous defer registrations lower to native nested try/finally, without cleanup callbacks or a registration stack. Scope, hoisting and disposal boundaries can require the conservative path. Dynamic registrations retain callbacks and reverse-order draining; async cleanup also awaits work. A specialized native loop can be much cheaper than registering a cleanup for each iteration, so measure allocation-sensitive loops in your actual application.
Direct-return switch expressions use native switch statements. Standalone identifier initializers use a result temporary and labelled branches. Other expression positions may need a synchronous lexical arrow IIFE. General component-child collection uses a local array and ordered pushes. Enum patterns add the checks and bindings their emitted code requires.
The optional @swiftuijs/twill-runtime package shares selected dynamic synchronous cleanup helpers when you explicitly choose external emission. Inline output is the default. Sharing can reduce uncompressed duplication across many modules while leaving gzip nearly unchanged, and a single module can grow. It does not remove cleanup registration costs. See runtime helpers and inspect production bundles.
Tool downloads and application bundles are different
The compiler, formatter, linter and editor are development tools. Their installed sizes are not application runtime overhead. Your application includes its emitted JavaScript, existing libraries and any runtime or shell package it explicitly imports. Twill 0.4.1 reduces duplicated parser/engine downloads and defer editor formatting and CLI backends. These changes preserve the emitted application code. See the toolchain comparison for exact measurement scopes and raw samples. CI checks representative emitted-output and distribution budgets separately; those budgets are not a size guarantee for arbitrary applications.
Compilation and editor feedback
Source transformation, TypeScript emission, project checking and bundler optimization are separate stages. A syntax-transform timing excludes process startup, filesystem discovery, dependency-heavy type checking and production bundling. Measure the complete command you intend to use.
The compiler reuses validated project configuration, and the editor reuses unchanged snapshots and transforms. Edits still require synchronization and checking of affected code. Fast repeated diagnostics for an unchanged file do not describe typing latency after an edit or VS Code UI responsiveness.
For scale, an older Linux/Node 24.19 synthetic mixed project with 1,002 source files measured about 1,020 ms for a cold check and 71/101 ms for edited-hover p50/p95. These observations exclude VS Code rendering and the native TS-server bridge; they are not a responsiveness target. The mixed-project measurement records the fixture, scope and memory observations. Profile your project's dependencies and editing patterns before drawing a conclusion.
Script startup and compilation caching
Running .twill source starts Node and loads the execution adapter. A compilation miss also initializes the compiler and transforms the source. Successful compilations can be cached across launches after validating source contents, project configuration and compiler/dependency identities. A valid hit skips compiler initialization, but it still starts Node, validates the cache and executes the script and its imports.
Measure these paths separately:
- First execution with an empty cache.
- Repeated execution with valid cached modules.
- Execution after editing an imported module or configuration.
- Prebuilt or exported JavaScript running directly in Node.
Earlier Linux/Node 24 source-cache measurements reported roughly 514 ms uncached, 544 ms with an empty cache, 157 ms with valid hits and 44 ms for the native reference. They illustrate why a cache hit and a cold start are different workloads; they are not current-version startup promises. Original cache measurements retain all samples and identities.
The current runner uses synchronous Node hooks where available and retains the compatibility adapter on supported older engines. This avoids Twill's DEP0205 warning on Node 26. The 0.3.1 loader comparison measures this adapter change separately; warning removal does not establish a universal startup speedup.
Exported or prebuilt JavaScript avoids source compilation at launch. See shell scripting for cache configuration and privacy boundaries, and adoption for native export.
Optional Node shell SDK
@swiftuijs/twill-shell is an optional subprocess library, independent of the language runtime. It uses Node spawn/streams with zero production dependencies. Running an external program does not make that program's own work faster.
Literal argv, bounded capture, input/output coordination and awaited cancellation/timeout teardown have costs. Inherited or discarded output avoids retaining returned capture data. Byte limits bound captured streams, not total process heap or RSS. Compare the SDK with handwritten Node that provides equivalent behavior and uses the same I/O policy.
The retained 0.3.0 Linux/Node 24 comparison found the following paired median wall ratios against equivalent handwritten Node:
| Workload | SDK / handwritten Node |
|---|---|
| Native dual 1 MiB capture | 1.171× |
| Native full-duplex 1 MiB | 1.113× |
| 32 concurrent Node children | 1.000× |
| 128 concurrent Node children | 1.009× |
The first two workloads exceed the historical 1.10 target. Their measured costs were explicitly accepted for the Node replacement; the failed strict report remains intact. These are host-specific workload results, not native parity or a general application slowdown estimate. The complete measurement and acceptance retain confidence intervals, every workload, memory and cold-start observations, source/build identities and the explicit release decision.
The current SDK does not use the retired Rust addon. Its historical speedups and abrupt-disposal guarantees do not apply. Applications cancel and await outstanding operations before worker/process shutdown; forced termination cannot complete asynchronous cleanup. See execution and version boundaries.
Evaluate your application
Start with one representative module or script and an equivalent native baseline. Keep dependencies, Node version, hardware, production settings and I/O policies the same.
- Verify behavior, error paths and cleanup before comparing timings.
- Inspect emitted JavaScript and production bundle sizes for added work.
- Measure full builds and feedback after real edits, separately from unchanged-cache requests.
- Measure cold execution and warm paths independently. Include allocations and memory when they matter.
- Retain all samples and record the environment, source revision and build identity. Treat noisy results as uncertain rather than selecting a favorable run.
Measurement methodology and history
The benchmark archive preserves the original compiler, cleanup, branching, enum, project/editor, React source, optional-helper and shell reports, including failed reviews and retired implementations. Use it to inspect methods and reproduce a specific result. Different fixtures, versions and environments are not one comparable performance series.
Correctness and generated-output budgets are enforced separately from timing observations. Controlled-host timing targets are not portable guarantees across CI runners. Reproduction instructions are in the archive and the contributor guide.
Shared emission cleanup (0.4.0)
Twill 0.4.0 emits simple expression callbacks/render props/Vue slots and single explicit value-return callbacks/render props as concise arrows and eligible React JSX children as native nested JSX. Branch bindings and returned match/switch expressions reuse an existing braced scope where direct eval (including captured eval) cannot observe the change, even after preceding statements; eligible implicit callback returns use native branches without another IIFE. General expression and direct-eval boundaries, required cleanup functions, subject/tag snapshots, per-arm lexical scopes and erased type witnesses remain.
The canonical playground examples share one regression suite through the actual public compiler and generated-code formatter. Native differential execution, framework rendering, source mappings, strict checking and the existing minified-output budgets validate the cleanup. No runtime speedup or broad byte-parity claim follows from fewer TSX braces. These emission changes require 0.4.0 or newer; earlier timing reports above retain their original versions.