28. Tooling

bun create vibelang my-app        # or: npm create vibelang@latest my-app
cd my-app
bun run build
bun run start
bun run test
bun run dev
bun x --no-install vibelang --noEmit

VibeLang 0.0.2 installs from npm as unscoped packages: vibelang, vibelang-runtime, vibelang-vite, vibelang-unplugin, create-vibelang, and one vibelang-<os>-<cpu> package per platform. create-vibelang copies the starter, pins the VibeLang packages to its own version, and installs dependencies; --no-install skips installation. Projects need Node 26 or later and Bun 1.4 or later. The compiler is a native binary: vibelang lists one package per platform as an optional dependency, and the package manager installs the one that matches the machine, the per-platform distribution D30 planned:

Version 0.0.2 ships darwin-arm64, darwin-x64, linux-arm64, linux-x64, win32-arm64, and win32-x64 binaries. All six are cross-compiled; the end-to-end npm and Bun rehearsal runs on Linux x64.

To work on VibeLang itself, install from a checkout instead. sh scripts/setup.sh requires Go, Bun, and Node on PATH; the tested versions are Go 1.26 (with Go 1.27 downloaded automatically), Bun 1.4.1, and Node 26.10. Setup builds packages/compiler/native/vibelang, installs and builds the runtime, and copies templates/app into ~/.bun-create/vibelang, a local template that bun create vibelang prefers over the npm package. That template uses absolute file: dependencies on the checkout's compiler and Vite packages and on the runtime tarball that setup packs (D120). Keep the checkout available; after updating it, rerun setup and run bun update vibelang-runtime vibelang vibelang-vite in projects created from it.

Setup links ~/.local/bin/vibelang when that directory is already on PATH and no unrelated executable occupies the path. Project scripts find their own compiler without that global link. VIBELANG_BINARY overrides the launcher's native binary. Setup preserves unrelated templates and never edits shell configuration.

Packages and versions

The starter pins effect, @effect/platform-node, and @effect/vitest to 4.0.5, and Vitest to 5.0.5. The runtime checks Effect's version on load. The compiler is the TypeScript 7.1 checker, with ordinary TypeScript semantics for .ts files (D30). Its emitted declarations are ordinary .d.ts files.

vibelang accepts TypeScript compiler flags: bare vibelang checks and emits, --noEmit checks, --watch watches, and -b builds references. The same native binary exposes --lsp --stdio and the upstream --api transport. The current Vite plugin uses subprocess compilation instead of the API transport (D105, amending D31).

Building and testing

The starter's configuration emits Node ESM into dist/:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "sourceMap": true,
    "rootDir": "src",
    "outDir": "dist",
    "noEmitOnError": true,
    "rewriteRelativeImportExtensions": true,
    "skipLibCheck": true,
    "types": []
  },
  "include": ["src/**/*.vibe"]
}

build runs vibelang. start builds and runs Node with --enable-source-maps. dev builds once, then runs the compiler watcher and Node output watcher; Ctrl+C stops both. Libraries can add declaration and declarationMap to emit declarations. The starter does not enable them.

Import local sources as ./welcome.vibe or ./format.ts. The compiler emits .js specifiers and declarations that name .js outputs (D31). In .ts, ./welcome.js resolves to welcome.vibe. Only .vibe sources are selected by the starter's include glob; imported .ts integrations also join the program.

The starter tests source files through the Vite plugin:

// TypeScript (.ts)
// vitest.config.ts
import { defineConfig } from "vitest/config"
import vibelang from "vibelang-vite"
 
export default defineConfig({
  plugins: [vibelang()],
  test: { include: ["src/**/*.test.vibe"] }
})

Register it.effect from @effect/vitest at the top level or in describe (D38). Effect's packages are trusted, so call assert from @effect/vitest directly: assert.strictEqual(actual, expected), whose failure is a defect that fails the test. Keep another library's assertions inside a hatch, with the values as inputs: sync((actual) => check(actual), actual). bun run test needs no prior build and maps assertion failures to .vibe lines.

For a Vite application, add the same plugin to vite.config.ts. The plugin runs one compiler subprocess for the project on the first request and after source changes. Requests share compilation. It emits JavaScript and source maps into its own directory under node_modules/.vibelang/, reports errors in the terminal and overlay, and invalidates all loaded .vibe modules and their importers after an edit. It does not compare exported contracts or use the API transport yet. Sources must stay under Vite's root so emit paths and source maps agree (D107). Its README documents project and compiler overrides.

The editor

The server is the fork's own, vibelang --lsp --stdio, from the project's compiler (D32). The same binary identifies as VibeLang 0.0.2 (TypeScript 7.1.0-dev) with --version; there is no separate compiler entry point (D75). vibelang ships the extension as editor/vibelang.vsix. Install it from a project:

code --install-extension node_modules/vibelang/editor/vibelang.vsix
# Or use cursor --install-extension with the same path.

Open the project directory so the extension finds its local compiler. Install the extension again after updating vibelang. In a checkout, setup also builds the extension and prints its path.

The extension finds vibelang from vibelang.server.path, then the nearest node_modules/.bin/vibelang, then PATH. It requires a trusted workspace (D79). Its grammar reuses VS Code's TypeScript grammar under source.vibe, with inner .ts scopes so existing themes apply.

For .ts ownership, disable VS Code's built-in TypeScript extension, or use Cursor's useTsgo setting (D76). The extension serves .vibe while the built-in TypeScript extension remains active, but leaves .ts to that extension. Do not set typescript.validate.enable to false: this server reads that setting too and would hide its VibeLang diagnostics.

Other editors can configure their LSP client for .vibe and .ts, with tsconfig.json as the root marker, and disable their other TypeScript server for this project. Add *.vibe linguist-language=TypeScript to .gitattributes for GitHub highlighting.

Hover shows a running call's success value as "Runs here and returns T", and a plain helper's direct signature alongside its TypeScript-facing type (D77). Prelude names and service members complete in scope (D78). A method of an Effect data type hovers as the function it calls, "Method syntax: calls Option.getOrElse(maybe, …)", and completes after a dot (D152). A call passed by name hovers as "Passed by name to fork as a program" (D147), and so does a pipe's topic that passes its left side by name; any other topic hovers as its value, "(topic) %: T" (D155). TypeScript files retain TypeScript hover behavior. D33's control-class hover text and catch-specific completions remain design targets. Quick fixes exist for retired spellings and for the EK48xx rules whose repair is mechanical (D240). Refactors, code actions of kind refactor.rewrite, write or remove a function's contract, convert an interface to a schema declaration, convert an async function to a VibeLang function, with or without an error declaration per await, convert nested calls to a |> pipe and back, and toggle x.pipe(f) and pipe(x, f) (D245). A layer's hover lists what it provides, needs, and fails with, and wire's hover the order it builds its layers in; a Duration.Input string, the name in Schema.brand("…"), and the codes of an @vibelang-diagnostics comment complete (D246). Diagnostic messages include repair suggestions as text; the current compiler does not implement those editor refactors.

Diagnostics

Every EK diagnostic before EK4801 is an error, except seven. Each error marks code that has no meaning, or code whose generated output would break a rule of Parts II and III, so none can be lowered and // @ts-expect-error does not apply to them; it keeps its TypeScript meaning for TypeScript's own codes. Five warnings mark retired spellings that still compile the same: EK1009, the old with spelling of a provide block; EK2112, a catch clause that tests a failure's type; EK2113, a catch clause typed Cause; EK2120, a service class or control class declaration; and EK2121, a layer declaration. Each has a quick fix. The other two exceptions are policy, not soundness: EK2004, an Effect try block with E = never, or a catch expression with no expected errors; defects pass through (D260), is a warning by default, and EK4403, a clock or randomness read, is an error by default. A project may set either to "error", "warning", or "off" in compilerOptions.vibelang.diagnostics; an EK4403 read then compiles as a trusted sync call that tests cannot control.

EK4801-EK4825 carry the rules of Effect's language service that VibeLang's syntax does not already rule out (D240). They are lint, not soundness: each has a default category, error, warning, or off, and every one except EK4813, which stands in for TypeScript's TS2339, can be set in compilerOptions.vibelang.diagnostics or by a comment (D241):

// @vibelang-diagnostics EK4818:warning            from here to the end of the file
// @vibelang-diagnostics-next-line EK4801:off       the next line only
// @vibelang-diagnostics *:off                      every adjustable code

A later comment overrides an earlier one, and within one comment a code named on its own overrides *. D266 supersedes D242: every EK diagnostic is restricted to .vibe files. Ordinary TypeScript sources keep TypeScript diagnostics regardless of these settings.

vibelang exits non-zero when any error is reported. The CLI prints error EK1003:; LSP sends source EK and numeric code 1003, which VS Code displays as EK(1003) (D61). Diagnostics print at .vibe spans, in the same form as the examples in this document, in the terminal, the editor, and Vite's overlay.

The diagnostic registry reserves these codes. This table describes each rule and the intended repair (D33, D53). A registry entry does not prove that its check or editor code action is implemented; the acceptance suite and compiler README track coverage. Repairs below are suggestions, not shipped code actions:

Linting

D35 assigns type and language diagnostics to vibelang and reserves type-aware linting for .ts files. A stock TypeScript checker models different call semantics and cannot type-check VibeLang correctly. Run vibelang --noEmit for .vibe checking. vibelang-oxlint-config is not shipped, and Vite Plus integration has no acceptance coverage yet. Do not install an unpublished lint-config package from the registry.

Debugging

vibelang writes source maps when sourceMap is on, and the Vite plugin always serves them. Each map records original .vibe positions on the lowered AST through TypeScript emit, so any debugger that reads standard source maps maps breakpoints and paused frames to .vibe lines: VS Code's JavaScript debugger for Node.js, Bun, and Chrome targets; Chrome and Edge DevTools; and JetBrains IDEs.

Paused on breakpoint, requestApproval  checkout.vibe:22
Call stack (JavaScript)
  requestApproval            checkout.vibe:22         the running VibeLang function
  runLoop                    effect/dist/internal/effect.js
  evaluate                   effect/dist/internal/effect.js

What a debugger shows follows from the frame invariant (Chapter 26):

• One VibeLang frame at a time. Compiled functions are generator functions named after their source, so the running function appears by name at its .vibe line. Its callers are frames on the fiber's _stack, not JavaScript activations, so the debugger's call stack shows Effect's run loop below it, not the VibeLang call chain.
• Regions are closures named after their function and block: profile$try, profile$catch, profile$finally, profile$using.
• Clauses and producers. A clause is a generator function named after its operation member (approve), and a producer's body is one named after the producer (lines). A breakpoint in a clause shows the clause; the handled program's frames are inside k, a heap value, and appear again when the program resumes. A breakpoint in a producer shows the producer, and the loop body runs in the clause of the for...of that iterates it.
• Stepping over a call that pauses continues on a later run-loop step, so the debugger steps into Effect's run loop; set a breakpoint on the next line instead, as with Effect.gen code today.
• Logical call stacks across calls and suspensions come from spans: set tracing to "exported" or "all", and use Effect's DevTools layer (effect/devtools) with its VS Code extension, which shows fibers and the span stack.