Getting Started

These guides teach VibeLang one topic at a time and also serve as a reference while you build. Start with Welcome, or jump to the subject you need.

Create and run your first project

bun create vibelang@latest my-app
cd my-app
bun run start
bun run test

With npm, run npm create vibelang@latest my-app. The starter prints:

Hello, VibeLang!
Recovered from EmptyName

src/greeting.vibe defines a greeting function and an EmptyName tagged error. src/main.vibe declares the Greeter service, supplies its Layer.succeed layer, recovers a typed failure with try/catch, and exports main, which node dist/main.js runs with NodeRuntime.runMain. src/greeting.test.vibe uses it.effect to test success and recovery. Vitest compiles src/**/*.test.vibe through vibelang-vite; tests need no prior build.

Run bun run dev to compile on changes and restart Node when output changes. Press Ctrl+C to stop both watchers. For diagnostics and hovers in VS Code or Cursor, install the extension that ships in vibelang, then open the project:

code --install-extension node_modules/vibelang/editor/vibelang.vsix

See Installation for prerequisites, supported platforms, editor setup, and adding VibeLang to an existing project.

Guides and reference material

// run: Console.log(Effect.provide(main(), Logger.layer([sync(() => Logger.make(({ message }) => console.log(...(message as unknown[]))))])))
function main() {
  const label = "first program"
  log(label)
  return label.length
}
// number!!
// Output: first program
// Output: 13

Read The Effect Type to understand this function's contract, Creating Effects to add failures, and Running Effects to execute it at an application boundary. Each guide explains a use case. The Effect 4 API reference lists library signatures, whose program arguments become zero-argument functions in VibeLang.

Documentation versions

These pages target Effect 4.0.5 and the language decisions recorded with this repository. When opening upstream documentation, select version 4. Effect 3 examples use a different library version and do not establish which APIs are available here.

The upstream site also documents newer changes. Check a signature against your installed package when it differs from an example on these pages.

Finding a subject

The directories group guides by task:

• Error management: failures, recovery, retry, and timeouts.
• Concurrency: bounded parallel work and fiber lifetimes.
• Requirements: services and layers.
• Resources: acquisition and cleanup.
• Schema: decoding and validating external data.
• Observability: logs, metrics, spans, and fibers.
• Streams: incremental processing with backpressure.

Use each page's headings to find a specific operation. In a Markdown reader, follow the outline or search for an API name. The numbered file names preserve the learning sequence without requiring you to read every page in order.

Using documentation with language models

Provide the relevant VibeLang guide alongside the Effect API signature. State that every function is an Effect, calls run, and a call passed where an operator expects a program is passed by name, as in fork(fetchReport()). Include your error and service declarations so generated code has enough information to preserve the contract.

Use compiler feedback and focused tests to check the result. Effect's TypeScript tooling applies to .ts integration code; the Devtools page explains VibeLang's compiler, language server, linting, and debugging setup.

The matching Effect page: effect.website/docs/v4/getting-started