{"id":16013,"library":"effect-start","title":"Effect Start Framework","description":"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.","status":"active","version":"0.36.0","language":"javascript","source_language":"en","source_url":null,"tags":["javascript"],"install":[{"cmd":"npm install effect-start","lang":"bash","label":"npm"},{"cmd":"yarn add effect-start","lang":"bash","label":"yarn"},{"cmd":"pnpm add effect-start","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Optional peer dependency for interacting with LibSQL databases.","package":"@libsql/client","optional":true},{"reason":"Core peer dependency for the Effect runtime and ecosystem. Required for all applications.","package":"effect","optional":false},{"reason":"Optional peer dependency for interacting with MS SQL Server databases.","package":"mssql","optional":true}],"imports":[{"note":"Main entrypoint for serving the application. `effect-start` is ESM-only.","wrong":"const Start = require('effect-start')","symbol":"Start","correct":"import { Start } from 'effect-start'"},{"note":"Used for configuring file-based routing. It's a named export.","wrong":"import FileRouter from 'effect-start'","symbol":"FileRouter","correct":"import { FileRouter } from 'effect-start'"},{"note":"The `layer` method is a static property of the `Start` object, used to compose application layers.","wrong":"new Start.Layer()","symbol":"Start.layer","correct":"Start.layer(...)"}],"quickstart":{"code":"import { FileRouter, Start } from \"effect-start\";\n\n// This layer applies configuration and changes the behavior of the server.\n// It expects a FileRouter.layer, which automatically loads routes.\nexport default Start.layer(\n  FileRouter.layer({\n    // Specifies how to dynamically load the generated routes file.\n    // `routes.gen.ts` is typically created by a build step or dev server.\n    load: () => import(\"./routes/routes.gen.ts\"),\n    // Provides a path hint for the router, useful for `import.meta.resolve`\n    path: import.meta.resolve(\"./routes/routes.gen.ts\"),\n  })\n);\n\n// This block ensures the server is only started when the file is run directly\n// (e.g., `bun run server.ts`), not when imported as a module.\nif (import.meta.main) {\n  // `Start.serve` takes a function that returns the main application layer,\n  // typically the default export of this `server.ts` file.\n  Start.serve(() => import(\"./server.ts\"));\n}","lang":"typescript","description":"This quickstart demonstrates the `server.ts` entrypoint, showing how to configure `effect-start` with file-based routing and serve the application."},"warnings":[{"fix":"Refer to the latest documentation, the `examples/` directory, and the project's changelog for updated patterns and migration guides.","message":"The 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.","severity":"breaking","affected_versions":">=0.1.0"},{"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.","message":"While 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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"`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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Always use ES Module `import` syntax for all imports related to `effect-start` and ensure your project is configured for ESM.","message":"`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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"The Tailwind CSS plugin path in `bunfig.toml` is incorrect, or `effect-start` is not correctly installed, or Bun cannot resolve the path.","error":"Error: Cannot find module 'effect-start/tailwind'"},{"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.","cause":"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.","error":"TypeError: Cannot read properties of undefined (reading 'layer') at Start.serve"},{"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.","cause":"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.","error":"Error: Failed to load module specifier './routes/routes.gen.ts'"}],"ecosystem":"npm"}