effect-start

library0.36.0jsnpmunverified

effect-start is a framework for building declarative full-stack applications by deeply integrating with the Effect ecosystem. Currently at version 0.36.0, the project is in its early stages of development, implying a rapid release cadence with potential for frequent, significant updates. It offers features such as automatic file-based routing, supporting frontend pages, backend API endpoints, and composable Route Layers for middleware. A key architectural design is a unified `server.ts` entrypoint for both development and production environments, aiming to eliminate configuration divergence. The framework also includes a lightweight Tailwind CSS plugin with minimal configuration, primarily demonstrated within the Bun runtime environment. Its declarative approach and reliance on Effect distinguish it from more imperative or traditional full-stack solutions, catering to developers already familiar with or interested in the Effect paradigm.

web-framework devops

npm install effect-start

package ↗homepage ↗

INSTALL

IMPORT

SIG · EFFECT-START

effect-start

web-frameworkjavascriptv0.36.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Start

✓ import { Start } from 'effect-start'

✗ const Start = require('effect-start')

Main entrypoint for serving the application. `effect-start` is ESM-only.

FileRouter

✓ import { FileRouter } from 'effect-start'

✗ import FileRouter from 'effect-start'

Used for configuring file-based routing. It's a named export.

Start.layer

✓ Start.layer(...)

✗ new Start.Layer()

The `layer` method is a static property of the `Start` object, used to compose application layers.

This quickstart demonstrates the `server.ts` entrypoint, showing how to configure `effect-start` with file-based routing and serve the application.

import { FileRouter, Start } from "effect-start"; // This layer applies configuration and changes the behavior of the server. // It expects a FileRouter.layer, which automatically loads routes. export default Start.layer( FileRouter.layer({ // Specifies how to dynamically load the generated routes file. // `routes.gen.ts` is typically created by a build step or dev server. load: () => import("./routes/routes.gen.ts"), // Provides a path hint for the router, useful for `import.meta.resolve` path: import.meta.resolve("./routes/routes.gen.ts"), }) ); // This block ensures the server is only started when the file is run directly // (e.g., `bun run server.ts`), not when imported as a module. if (import.meta.main) { // `Start.serve` takes a function that returns the main application layer, // typically the default export of this `server.ts` file. Start.serve(() => import("./server.ts")); }

effect-start --version

Debug

Known issues

breakingThe project is explicitly stated as 'early stage' (v0.36.0), indicating that APIs are subject to significant change, and breaking changes are highly probable across minor versions. Users should expect frequent updates and may need to adapt their code.

fix

Refer to the latest documentation, the `examples/` directory, and the project's changelog for updated patterns and migration guides.

affects: >=0.1.0

gotchaWhile not explicitly mandated, the documentation and examples heavily feature the Bun runtime (`bun add`, `bunfig.toml`). Users attempting to run `effect-start` with Node.js or Deno may encounter compatibility issues or missing features, particularly with tooling-related aspects like the Tailwind plugin configuration.

fix

It is recommended to use Bun for `effect-start` projects to ensure full compatibility and leverage all features as intended. If using other runtimes, thoroughly test compatibility.

affects: >=0.1.0

gotcha`effect-start` is built entirely on the Effect ecosystem. Developers new to Effect might face a steep learning curve understanding its declarative, functional, and highly typed patterns (e.g., Layers, Fibers, Streams, Schemas) which are fundamental to `effect-start`'s architecture.

fix

Familiarize yourself with the core concepts and patterns of the Effect library before diving deep into `effect-start`. The official Effect documentation and examples are excellent resources.

affects: >=0.1.0

gotcha`effect-start` is an ES Module (ESM) first framework, evidenced by the use of `import.meta.resolve` and `import.meta.main`. Attempting to use CommonJS `require()` syntax for importing `effect-start` modules will result in `ERR_REQUIRE_ESM` or similar errors.

fix

Always use ES Module `import` syntax for all imports related to `effect-start` and ensure your project is configured for ESM.

affects: >=0.1.0

Errors

Common errors & fixes

Error: Cannot find module 'effect-start/tailwind'

The Tailwind CSS plugin path in `bunfig.toml` is incorrect, or `effect-start` is not correctly installed, or Bun cannot resolve the path.

fix

Ensure `effect-start` is installed (`bun add effect-start`) and that `bunfig.toml` has `plugins = ["effect-start/tailwind"]` under `[serve.static]` exactly as specified in the documentation.

TypeError: Cannot read properties of undefined (reading 'layer') at Start.serve

The function passed to `Start.serve()` is not correctly returning a Layer, or the `server.ts` file's default export is not a valid Effect Layer.

fix

Verify that your `server.ts` file exports a default `Start.layer(...)` composition, and that `Start.serve(() => import("./server.ts"))` correctly imports and executes this. Ensure all inner layers are also correctly constructed.

Error: Failed to load module specifier './routes/routes.gen.ts'

The file-based router is configured to load `routes.gen.ts`, but this file does not exist or cannot be resolved at runtime. This file is typically generated by a build step or dev server process.

fix

Ensure your development server or build process is running and successfully generating `src/routes/routes.gen.ts`. Check the console for any errors during the route generation phase.

Upgrade

Version history

0.36.0latest on npm

Audit

Dependencies

@libsql/clientoptionalOptional peer dependency for interacting with LibSQL databases.

effectrequiredCore peer dependency for the Effect runtime and ecosystem. Required for all applications.

mssqloptionalOptional peer dependency for interacting with MS SQL Server databases.

Agent activity

12 hits · last 30 days

node

Resources

packagehttps://www.npmjs.com/package/effect-start ↗

homepagehttps://effect-start.com ↗