Twill for VS Code

Write clearer JavaScript and TypeScript, with the editor tools you already expect.

Twill is a TypeScript-based language with Swift-inspired syntax extensions. It extends TypeScript and TSX, using TypeScript's type system and adding: readable callbacks, explicit early exits, cleanup beside resource acquisition, and checked handling of business states. You write .twill or .twillx files; the Twill compiler turns them into ordinary JavaScript, using your existing libraries and framework runtimes.

This extension helps you write, understand and debug Twill in VS Code. It provides syntax highlighting, TypeScript completion and error checking, navigation, formatting and Node debugging. Use it for scripts, backend code, data processing, React or Vue applications.

Try the playground · Documentation · Report an issue

What does Twill look like?

An ordinary TypeScript callback chain:

const activeNames = users.filter((user) => user.active).map((user) => user.name);

The same operation in main.twill:

const activeNames = users.filter { .active }.map { .name };

Here, .active and .name refer to the callback's first argument. You can also name parameters explicitly: [1, 2, 3].map { value in value * 2 }. These callbacks compile to ordinary arrow functions, with contextual types inferred from the existing API.

Twill also helps with control flow:

function greeting(name: string | undefined): string {
  guard const value = name else {
    return 'Hello, guest';
  }
  return `Hello, ${value.toUpperCase()}`;
}

guard makes the failure path exit immediately. After the guard, TypeScript knows value is a string. Twill's other features include block-scoped defer for cleanup and switch expressions checked against ordinary TypeScript unions. See practical patterns for examples and language semantics for the exact rules.

What can I do with this extension?

The extension includes its editing tools. To run or build your application, install the compiler package, @swiftuijs/twill, in that application. The compiler also provides twill check for whole-project checking.

Your first Twill program

This walkthrough creates a small Node application. It requires Node 20.19+ or 22.12+ and VS Code 1.95.3+. You can also explore the syntax without installing anything in the browser playground.

1. Install the extension

In VS Code, open Extensions, search for Twill by forth.ink, and click Install. Or use:

code --install-extension forth-ink.twill

2. Create a project and install the compiler

Run these commands in your terminal:

mkdir twill-demo
cd twill-demo
npm init -y
npm pkg set type=module
npm install --save-dev @swiftuijs/twill
mkdir src

Open the twill-demo folder in VS Code. If you use pnpm, the compiler installation command is pnpm add -D @swiftuijs/twill.

3. Add your source and TypeScript settings

Create src/main.twill:

const users = [
  { name: 'Ada', active: true },
  { name: 'Linus', active: false },
  { name: 'Grace', active: true },
];

const activeNames = users.filter { .active }.map { .name };
console.log(activeNames);

Create tsconfig.json in the project root:

{
  "compilerOptions": {
    "strict": true,
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler"
  },
  "include": ["src/**/*"]
}

Twill uses your normal TypeScript settings. No twill.config.json is needed. Existing projects can keep their tsconfig and include Twill files alongside their TS/JS files.

In the editor, hover over activeNames to see its inferred string[] type. Change .active to .missing to see a type error, then undo it. Open the command palette and choose Twill: Show Generated TypeScript to see how the callbacks compile.

4. Check and run it

From the project root:

npx twill check -p tsconfig.json
node --enable-source-maps --import @swiftuijs/twill/register src/main.twill

The program prints:

[ 'Ada', 'Grace' ]

For debugging, open src/main.twill, set a breakpoint on console.log, and choose Twill: Debug Current File from the command palette. The command runs the file using your project's dependencies and environment.

Use it in an existing application

Install @swiftuijs/twill locally, add your build tool's adapter, and start with one file. Native .ts, .tsx, .js and .jsx files keep their standard syntax and can import Twill modules or be imported by them.

For a Vite application, add the plugin to the existing configuration:

import { defineConfig } from 'vite';
import twill from '@swiftuijs/twill/vite';

export default defineConfig({ plugins: [twill()] });

React applications should use the React Vite adapter for Fast Refresh. React and Vue component libraries use their normal imports, props, children and slots. Twill requires no component registry or wrapping API.

See React and Vue, other build tools and mixed TS/JS projects for application setup. Run twill check before building; native tsc cannot parse Twill source. Libraries can emit standard declarations.

Enable format-on-save

The extension includes a formatter. Add this to .vscode/settings.json:

{
  "[twill-typescript]": {
    "editor.defaultFormatter": "forth-ink.twill",
    "editor.formatOnSave": true
  },
  "[twill-tsx]": {
    "editor.defaultFormatter": "forth-ink.twill",
    "editor.formatOnSave": true
  }
}

The bundled formatter uses editor indentation and Prettier defaults. For a shared .prettierrc and CLI formatting, use the standard Prettier extension with @swiftuijs/twill-formatter. Optional ESLint integration uses @swiftuijs/twill-linter and Microsoft's ESLint extension. Follow the formatter and linter guide.

Useful commands

Open the command palette with Ctrl+Shift+P on Windows/Linux or Cmd+Shift+P on macOS.

Browser applications use their existing browser and framework developer tools. See the debugging guide for custom launch settings.

Troubleshooting and support

• Native TypeScript cannot resolve a Twill import? Open the application folder containing its tsconfig, then run TypeScript: Restart TS Server.
• Missing component or callback suggestions? Check your framework types and JSX settings, repair nearby syntax errors, and inspect Twill: Show Project Diagnostics.
• A rename or quick fix is unavailable? Some edits cross generated syntax and cannot be mapped safely; these edits are withheld. General refactoring and fix-all are outside the supported workflow.
• Need an offline install? Download twill.vsix from the matching GitHub release and choose Extensions → … → Install from VSIX.

Twill's 0.x release line is experimental. The checker and extension use TypeScript 5.9 semantics. Review the compatibility and support guide for tested versions and boundaries.

For a bug report, include a small source example, your extension/compiler versions, VS Code and Node versions, and relevant project settings. Use GitHub Issues.

MIT licensed · Built by forth.ink · Source code