effect-start 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Rafał Gutkowski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,109 @@
+# Effect Start
+
+Build declarative full-stack apps with Effect.
+
+This project is in its early stage. However, the code is well documented so you should be able to figure out how to use it
+by checking out `examples/` directory.
+
+## Development
+
+### Configuration
+
+`server.ts` is a main entrypoint for all environments. No more divergence between dev and prod!
+
+It exports a layer that applies configuration and changes the behavior of the server:
+
+```typescript
+import { Start } from "effect-start"
+import { BunTailwindPlugin } from "effect-start/bun"
+
+export default Start.make(
+  // enable file-based router
+  Start.router(() => import("./routes/_manifest")),
+  // bundle client-side code for the browser
+  Start.bundleClient({
+    entrypoints: [
+      "src/index.html",
+    ],
+    plugins: [
+      // enable TailwindCSS for client bundle
+      BunTailwindPlugin.make(),
+    ],
+  }),
+)
+```
+
+### File-based Routing
+
+Effect Start provides automatic file-based routing with support for frontend pages, backend endpoints, and stackable layouts.
+
+```
+src/routes/
+├── _layout.tsx          # Root layout
+├── _page.tsx            # Home page (/)
+├── about/
+│   ├── _layout.tsx      # Nested layout for /about/*
+│   └── _page.tsx        # Static route (/about)
+├── users/
+│   ├── _page.tsx        # Users list (/users)
+│   └── $id/_page.tsx    # Dynamic route (/users/:id)
+└── $/_page.tsx          # Splat/catch-all (/**)
+```
+
+```ts
+import { FileRouter } from "effect-start"
+
+// Generate route manifest and watch for changes
+const routerLayer = FileRouter.layer(import.meta.resolve("routes"))
+```
+
+**Note:** Ensure `FileRouter.layer` is provided after any bundle layer to guarantee the manifest file is properly generated before bundling.
+
+### Tailwind CSS Support
+
+Effect Start includes built-in support for Tailwind CSS:
+
+```ts
+import { Start } from "effect-start"
+import { BunTailwindPlugin } from "effect-start/bun"
+
+const ClientBundle = Start.bundleClient({
+  entrypoints: [
+    "./src/index.html",
+  ],
+  plugins: [
+    BunTailwindPlugin.make(),
+  ],
+})
+
+export default Start.make(
+  ClientBundle,
+)
+
+if (import.meta.main) {
+  Start.serve(() => import("./server"))
+}
+```
+
+Then in your main CSS files add following file:
+
+```css
+@import "tailwindcss";
+```
+
+### Cloudflare Tunnel
+
+Tunnel your local server to the Internet with `cloudflared`
+
+```ts
+import { Start } from "effect-start"
+import { CloudflareTunnel } from "effect-start/x/cloudflare"
+
+export default Start.make(
+  CloudflareTunnel.layer(),
+)
+
+if (import.meta.main) {
+  Start.serve(() => import("./server"))
+}
+```

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "effect-start",
+  "version": "0.9.0",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": "./src/index.ts",
+    "./Router": "./src/Router.ts",
+    "./Route": "./src/Route.ts",
+    "./Datastar": "./src/Datastar.ts",
+    "./EncryptedCookies": "./src/EncryptedCookies.ts",
+    "./bun": "./src/bun/index.ts",
+    "./client": "./src/client/index.ts",
+    "./FileSystemExtra": "./src/FileSystemExtra.ts",
+    "./package.json": "./package.json",
+    "./jsx-runtime": "./src/jsx-runtime.ts",
+    "./jsx-dev-runtime": "./src/jsx-runtime.ts",
+    "./hyper": "./src/hyper/index.ts",
+    "./x/*": "./src/x/*/index.ts"
+  },
+  "scripts": {
+    "format": "bunx dprint fmt",
+    "deploy": "bunx npm publish --access public"
+  },
+  "dependencies": {
+    "@effect/platform": ">=0.82",
+    "@effect/platform-bun": ">=0.65"
+  },
+  "peerDependencies": {
+    "typescript": "^5.8.3",
+    "effect": ">=3.16.4"
+  },
+  "peerDependenciesMeta": {
+    "@tailwindcss/node": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@dprint/json": "^0.21.0",
+    "@dprint/markdown": "^0.20.0",
+    "@dprint/typescript": "^0.95.12",
+    "@effect/language-service": "^0.23.3",
+    "@tailwindcss/node": ">=4.1.8",
+    "@types/bun": "^1.2.15",
+    "@types/react": "^19.1.6",
+    "@types/react-dom": "^19.1.6",
+    "dprint-cli": "^0.4.0",
+    "dprint-markup": "nounder/dprint-markup",
+    "effect": "^3.19.4",
+    "effect-memfs": "nounder/effect-memfs#a976bb0",
+    "ts-namespace-import": "nounder/ts-namespace-import#140c405"
+  },
+  "files": [
+    "src/",
+    "package.json"
+  ]
+}

package/src/Bundle.ts

@@ -0,0 +1,167 @@
+import {
+  Context,
+  Data,
+  Effect,
+  pipe,
+  PubSub,
+} from "effect"
+import * as Schema from "effect/Schema"
+import { importBlob } from "./JsModule.ts"
+
+export const BundleEntrypointMetaKey: unique symbol = Symbol.for(
+  "effect-start/BundleEntrypointMetaKey",
+)
+
+export type BundleOutputMetaValue = {}
+
+/**
+ * Generic shape describing a bundle across multiple bundlers
+ * (like bun, esbuild & vite)
+ */
+export const BundleManifestSchema = Schema.Struct({
+  entrypoints: Schema.Record({
+    key: Schema.String,
+    value: Schema.String,
+  }),
+  artifacts: Schema.Array(
+    Schema.Struct({
+      path: Schema.String,
+      type: Schema.String,
+      size: Schema.Number,
+      hash: pipe(
+        Schema.String,
+        Schema.optional,
+      ),
+      imports: pipe(
+        Schema.Array(
+          Schema.Struct({
+            path: Schema.String,
+            kind: Schema.Literal(
+              "import-statement",
+              "require-call",
+              "require-resolve",
+              "dynamic-import",
+              "import-rule",
+              "url-token",
+              "internal",
+              "entry-point-run",
+              "entry-point-build",
+            ),
+          }),
+        ),
+        Schema.optional,
+      ),
+    }),
+  ),
+})
+
+export type BundleManifest = typeof BundleManifestSchema.Type
+
+const BundleEventChange = Schema.TaggedStruct("Change", {
+  path: Schema.String,
+})
+
+const BundleEventBuildError = Schema.TaggedStruct("BuildError", {
+  error: Schema.String,
+})
+
+export const BundleEvent = Schema.Union(
+  BundleEventChange,
+  BundleEventBuildError,
+)
+
+export type BundleEvent = typeof BundleEvent.Type
+
+const IdPrefix = "effect-start/tags/"
+
+export type BundleKey = `${string}Bundle`
+
+export type BundleId = `${typeof IdPrefix}${BundleKey}`
+
+/**
+ * Passed to bundle effects and within bundle runtime.
+ * Used to expose artifacts via HTTP server and properly resolve
+ * imports within the bundle.
+ */
+export type BundleContext =
+  & BundleManifest
+  & {
+    // TODO: consider removing resolve: way of resolving URL should be
+    // the same regardless of underlying bundler since we have access
+    // to all artifacts already.
+    resolve: (url: string) => string | null
+    getArtifact: (path: string) => Blob | null
+    events?: PubSub.PubSub<BundleEvent>
+  }
+
+export class BundleError extends Data.TaggedError("BundleError")<{
+  message: string
+  cause?: unknown
+}> {}
+
+export const emptyBundleContext: BundleContext = {
+  entrypoints: {},
+  artifacts: [],
+  resolve: () => null,
+  getArtifact: () => null,
+}
+
+export const handleBundleErrorSilently = (
+  effect: Effect.Effect<BundleContext, BundleError>,
+): Effect.Effect<BundleContext, never> =>
+  pipe(
+    effect,
+    Effect.catchTag("BundleError", (error) =>
+      Effect.gen(function*() {
+        yield* Effect.logError("Bundle build failed", error)
+        return emptyBundleContext
+      })),
+  )
+
+export const Tag = <const T extends BundleKey>(name: T) => <Identifier>() =>
+  Context.Tag(`${IdPrefix}${name}` as BundleId)<
+    Identifier,
+    BundleContext
+  >()
+
+export type Tag = Context.Tag<
+  BundleId,
+  BundleContext
+>
+
+export class ClientBundle extends Tag("ClientBundle")<ClientBundle>() {}
+export class ServerBundle extends Tag("ServerBundle")<ServerBundle>() {}
+
+/**
+ * Lodas a bundle as a javascript module.
+ * Bundle must have only one entrypoint.
+ */
+export function load<M>(
+  bundle: Effect.Effect<BundleContext, BundleError>,
+): Effect.Effect<M, BundleError> {
+  return Effect.gen(function*() {
+    const context = yield* bundle
+    const [artifact, ...rest] = Object.values(context.entrypoints)
+
+    if (rest.length > 0) {
+      return yield* Effect.fail(
+        new BundleError({
+          message: "Multiple entrypoints are not supported in load()",
+        }),
+      )
+    }
+
+    return yield* Effect.tryPromise({
+      try: () => {
+        const blob = context.getArtifact(artifact)
+
+        return importBlob<M>(blob!)
+      },
+      catch: (e) =>
+        new BundleError({
+          message: "Failed to load entrypoint",
+          cause: e,
+        }),
+    })
+  })
+}

package/src/BundleFiles.ts

@@ -0,0 +1,174 @@
+import * as FileSystem from "@effect/platform/FileSystem"
+import * as Array from "effect/Array"
+import * as Effect from "effect/Effect"
+import * as Function from "effect/Function"
+import * as Iterable from "effect/Iterable"
+import * as Record from "effect/Record"
+import * as S from "effect/Schema"
+import {
+  type BundleContext,
+  BundleError,
+  type BundleManifest,
+  BundleManifestSchema,
+} from "./Bundle.ts"
+
+/**
+ * Exports a bundle to a file system under specified directory.
+ */
+export const toFiles = (
+  context: BundleContext,
+  outDir: string,
+) => {
+  return Effect.gen(function*() {
+    const fs = yield* FileSystem.FileSystem
+    const manifest: BundleManifest = {
+      entrypoints: context.entrypoints,
+      artifacts: context.artifacts,
+    }
+
+    const normalizedOutDir = outDir.replace(/\/$/, "")
+
+    const bundleArtifacts = Function.pipe(
+      manifest.artifacts,
+      Array.map((artifact) =>
+        [artifact.path, context.getArtifact(artifact.path)!] as const
+      ),
+      Record.fromEntries,
+    )
+    const extraArtifacts = {
+      "manifest.json": new Blob([JSON.stringify(manifest, undefined, 2)], {
+        type: "application/json",
+      }),
+    }
+
+    const allArtifacts = {
+      ...bundleArtifacts,
+      ...extraArtifacts,
+    }
+
+    const existingOutDirFiles = yield* fs.readDirectory(normalizedOutDir).pipe(
+      Effect.catchAll(() => Effect.succeed(null)),
+    )
+
+    // check if the output directory is empty. if it contains previous build,
+    // remove it. Otherwise fail.
+    if (existingOutDirFiles && existingOutDirFiles.length > 0) {
+      if (existingOutDirFiles.includes("manifest.json")) {
+        yield* Effect.logWarning(
+          "Output directory seems to contain previous build. Overwriting...",
+        )
+
+        yield* fs.remove(normalizedOutDir, {
+          recursive: true,
+        })
+      } else {
+        return yield* Effect.fail(
+          new BundleError({
+            message: "Output directory is not empty",
+          }),
+        )
+      }
+    }
+
+    yield* fs.makeDirectory(normalizedOutDir, {
+      recursive: true,
+    })
+
+    // write all artifacts to files
+    yield* Effect.all(
+      Function.pipe(
+        allArtifacts,
+        Record.toEntries,
+        Array.map(([p, b]) =>
+          Function.pipe(
+            Effect.tryPromise({
+              try: () => b.arrayBuffer(),
+              catch: (e) =>
+                new BundleError({
+                  message: "Failed to read an artifact as a buffer",
+                  cause: e,
+                }),
+            }),
+            Effect.andThen((b) =>
+              fs.writeFile(
+                `${normalizedOutDir}/${p}`,
+                new Uint8Array(b),
+              )
+            ),
+          )
+        ),
+      ),
+      { concurrency: 16 },
+    )
+  })
+}
+
+/**
+ * Loads a bundle from a directory and returns a BundleContext.
+ * Expects the directory to contain a manifest.json file and all the artifacts
+ * referenced in the manifest.
+ */
+export const fromFiles = (
+  directory: string,
+): Effect.Effect<
+  BundleContext,
+  BundleError,
+  FileSystem.FileSystem
+> => {
+  return Effect.gen(function*() {
+    const fs = yield* FileSystem.FileSystem
+    const normalizedDir = directory.replace(/\/$/, "")
+    const manifest = yield* Function.pipe(
+      fs.readFileString(`${normalizedDir}/manifest.json`),
+      Effect.andThen((v) => JSON.parse(v) as unknown),
+      Effect.andThen(S.decodeUnknownSync(BundleManifestSchema)),
+      Effect.catchAll((e) =>
+        Effect.fail(
+          new BundleError({
+            message: `Failed to read manifest.json from ${normalizedDir}`,
+            cause: e,
+          }),
+        )
+      ),
+    )
+    const artifactPaths = Array.map(manifest.artifacts, (a) => a.path)
+    const artifactBlobs = yield* Function.pipe(
+      artifactPaths,
+      Iterable.map((path) => fs.readFile(`${normalizedDir}/${path}`)),
+      Effect.all,
+      Effect.catchAll((e) =>
+        new BundleError({
+          message: `Failed to read an artifact from ${normalizedDir}`,
+          cause: e,
+        })
+      ),
+      Effect.andThen(Iterable.map((v, i) =>
+        new Blob([v.slice(0)], {
+          type: manifest.artifacts[i].type,
+        })
+      )),
+    )
+    const artifactsRecord = Function.pipe(
+      Iterable.zip(
+        artifactPaths,
+        artifactBlobs,
+      ),
+      Record.fromEntries,
+    )
+
+    const bundleContext: BundleContext = {
+      ...manifest,
+      // TODO: support fullpath file:// urls
+      // this will require having an access to base path of a build
+      // and maybe problematic because bundlers transform urls on build
+      resolve: (url: string) => {
+        return manifest.entrypoints[url] ?? null
+      },
+      getArtifact: (path: string) => {
+        return artifactsRecord[path] ?? null
+      },
+    }
+
+    return bundleContext
+  })
+}

package/src/BundleHttp.test.ts

@@ -0,0 +1,160 @@
+import * as HttpRouter from "@effect/platform/HttpRouter"
+import * as HttpServerResponse from "@effect/platform/HttpServerResponse"
+import * as t from "bun:test"
+import {
+  Bundle,
+  BundleHttp,
+  effectFn,
+  TestHttpClient,
+} from "effect-start"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import IndexHtml from "../static/react-dashboard.html" with { type: "file" }
+import * as BunBundle from "./bun/BunBundle.ts"
+
+const effect = effectFn(
+  Layer.effect(
+    Bundle.ClientBundle,
+    BunBundle.buildClient(IndexHtml),
+  ),
+)
+
+t.it("entrypoint with specific uri", () =>
+  effect(function*() {
+    const App = HttpRouter.empty.pipe(
+      HttpRouter.get(
+        "/react-dashboard",
+        BundleHttp.entrypoint("../static/react-dashboard.html"),
+      ),
+    )
+    const Client = TestHttpClient.make(App)
+
+    const dashboardRes = yield* Client.get("/react-dashboard")
+    t
+      .expect(
+        dashboardRes.status,
+      )
+      .toBe(200)
+    t
+      .expect(
+        yield* dashboardRes.text,
+      )
+      .toStartWith("<!DOCTYPE html>")
+  }))
+
+t.it("entrypoint without uri parameter", () =>
+  effect(function*() {
+    const App = HttpRouter.empty.pipe(
+      HttpRouter.get(
+        "/",
+        BundleHttp.entrypoint(),
+      ),
+      HttpRouter.get(
+        "/index",
+        BundleHttp.entrypoint(),
+      ),
+      HttpRouter.get(
+        "/react-dashboard",
+        BundleHttp.entrypoint(),
+      ),
+      HttpRouter.get(
+        "/nonexistent",
+        BundleHttp.entrypoint(),
+      ),
+    )
+    const Client = TestHttpClient.make(App)
+
+    const indexRes = yield* Client.get("/").pipe(
+      Effect.catchTag(
+        "RouteNotFound",
+        () => HttpServerResponse.empty({ status: 404 }),
+      ),
+    )
+    t
+      .expect(
+        indexRes.status,
+      )
+      .toBe(404)
+
+    const indexPathRes = yield* Client.get("/index").pipe(
+      Effect.catchTag(
+        "RouteNotFound",
+        () => HttpServerResponse.empty({ status: 404 }),
+      ),
+    )
+    t
+      .expect(
+        indexPathRes.status,
+      )
+      .toBe(404)
+
+    const dashboardRes = yield* Client.get("/react-dashboard")
+    t
+      .expect(
+        dashboardRes.status,
+      )
+      .toBe(200)
+    t
+      .expect(
+        yield* dashboardRes.text,
+      )
+      .toStartWith("<!DOCTYPE html>")
+
+    const nonexistentRes = yield* Client.get("/nonexistent").pipe(
+      Effect.catchTag(
+        "RouteNotFound",
+        () => HttpServerResponse.empty({ status: 404 }),
+      ),
+    )
+    t
+      .expect(
+        nonexistentRes.status,
+      )
+      .toBe(404)
+  }))
+
+t.it("withEntrypoints middleware", () =>
+  effect(function*() {
+    const fallbackApp = Effect.succeed(
+      HttpServerResponse.text("Fallback", { status: 404 }),
+    )
+
+    const App = BundleHttp.withEntrypoints()(fallbackApp)
+    const Client = TestHttpClient.make(App)
+
+    const rootRes = yield* Client.get("/")
+    t
+      .expect(
+        rootRes.status,
+      )
+      .toBe(404)
+    t
+      .expect(
+        yield* rootRes.text,
+      )
+      .toBe("Fallback")
+
+    const dashboardRes = yield* Client.get("/react-dashboard")
+    t
+      .expect(
+        dashboardRes.status,
+      )
+      .toBe(200)
+    t
+      .expect(
+        yield* dashboardRes.text,
+      )
+      .toStartWith("<!DOCTYPE html>")
+
+    const nonexistentRes = yield* Client.get("/nonexistent")
+    t
+      .expect(
+        nonexistentRes.status,
+      )
+      .toBe(404)
+    t
+      .expect(
+        yield* nonexistentRes.text,
+      )
+      .toBe("Fallback")
+  }))