@livestore/adapter-node 0.4.0-dev.9 → 0.4.0

package/src/client-session/adapter.ts

@@ -1,19 +1,21 @@
 import { hostname } from 'node:os'
 import path from 'node:path'
+import type { URL } from 'node:url'
 import * as WT from 'node:worker_threads'
+
 import {
   type Adapter,
   type BootStatus,
   ClientSessionLeaderThreadProxy,
   IntentionalShutdownCause,
+  isWorkerTransportError,
   type LockStatus,
   type MakeSqliteDb,
   makeClientSession,
-  type SyncError,
   type SyncOptions,
-  UnexpectedError,
+  UnknownError,
 } from '@livestore/common'
-import { Eventlog, LeaderThreadCtx } from '@livestore/common/leader-thread'
+import { Eventlog, LeaderThreadCtx, streamEventsWithSyncState } from '@livestore/common/leader-thread'
 import type { LiveStoreSchema } from '@livestore/common/schema'
 import { LiveStoreEvent } from '@livestore/common/schema'
 import { loadSqlite3Wasm } from '@livestore/sqlite-wasm/load-wasm'
@@ -27,14 +29,14 @@ import {
   Fiber,
   FileSystem,
   Layer,
-  ParseResult,
+  Option,
   Queue,
   Schedule,
   Schema,
   Stream,
+  Subscribable,
   SubscriptionRef,
   Worker,
-  WorkerError,
 } from '@livestore/utils/effect'
 import { PlatformNode } from '@livestore/utils/node'
 import * as Webmesh from '@livestore/webmesh'
@@ -87,7 +89,43 @@ export interface NodeAdapterOptions {
   }
 }
 
-/** Runs everything in the same thread. Use `makeWorkerAdapter` for multi-threaded implementation. */
+/**
+ * Creates a single-threaded LiveStore adapter for Node.js applications.
+ *
+ * This adapter runs the leader thread (persistence and sync) in the same thread as
+ * your application. Suitable for CLI tools, scripts, and applications where simplicity
+ * is preferred over maximum performance.
+ *
+ * For production servers or performance-critical applications, consider `makeWorkerAdapter`
+ * which runs persistence/sync in a separate worker thread.
+ *
+ * @example
+ * ```ts
+ * import { makeAdapter } from '@livestore/adapter-node'
+ * import { makeWsSync } from '@livestore/sync-cf/client'
+ *
+ * const adapter = makeAdapter({
+ *   storage: { type: 'fs', baseDirectory: './data' },
+ *   sync: {
+ *     backend: makeWsSync({ url: 'wss://api.example.com/sync' }),
+ *   },
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // With DevTools support
+ * const adapter = makeAdapter({
+ *   storage: { type: 'fs', baseDirectory: './data' },
+ *   devtools: {
+ *     schemaPath: new URL('./schema.ts', import.meta.url),
+ *     port: 4242,
+ *   },
+ * })
+ * ```
+ *
+ * @see https://livestore.dev/docs/reference/adapters/node for setup guide
+ */
 export const makeAdapter = ({
   sync,
   ...options
@@ -96,7 +134,36 @@ export const makeAdapter = ({
 }): Adapter => makeAdapterImpl({ ...options, leaderThread: { _tag: 'single-threaded', sync } })
 
 /**
- * Runs persistence and syncing in a worker thread.
+ * Creates a multi-threaded LiveStore adapter for Node.js applications.
+ *
+ * This adapter runs the leader thread (persistence, sync, and heavy SQLite operations)
+ * in a separate worker thread, keeping your main thread responsive. Recommended for
+ * production servers and performance-critical applications.
+ *
+ * You must create a worker file that calls `makeLeaderWorker()` and pass its URL
+ * to this function.
+ *
+ * @example
+ * ```ts
+ * // In your main file:
+ * import { makeWorkerAdapter } from '@livestore/adapter-node'
+ *
+ * const adapter = makeWorkerAdapter({
+ *   storage: { type: 'fs', baseDirectory: './data' },
+ *   workerUrl: new URL('./livestore.worker.ts', import.meta.url),
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // In livestore.worker.ts:
+ * import { makeLeaderWorker } from '@livestore/adapter-node/worker'
+ * import { schema } from './schema'
+ *
+ * makeLeaderWorker({ schema })
+ * ```
+ *
+ * @see https://livestore.dev/docs/reference/adapters/node for setup guide
  */
 export const makeWorkerAdapter = ({
   workerUrl,
@@ -137,7 +204,8 @@ const makeAdapterImpl = ({
 }): Adapter =>
   ((adapterArgs) =>
     Effect.gen(function* () {
-      const { storeId, devtoolsEnabled, shutdown, bootStatusQueue, syncPayload, schema } = adapterArgs
+      const { storeId, devtoolsEnabled, shutdown, bootStatusQueue, syncPayloadEncoded, syncPayloadSchema, schema } =
+        adapterArgs
 
       yield* Queue.offer(bootStatusQueue, { stage: 'loading' })
 
@@ -157,7 +225,7 @@ const makeAdapterImpl = ({
       if (resetPersistence === true) {
         yield* shutdownChannel
           .send(IntentionalShutdownCause.make({ reason: 'adapter-reset' }))
-          .pipe(UnexpectedError.mapToUnexpectedError)
+          .pipe(UnknownError.mapToUnknownError)
 
         yield* resetNodePersistence({ storage, storeId })
       }
@@ -165,7 +233,7 @@ const makeAdapterImpl = ({
       yield* shutdownChannel.listen.pipe(
         Stream.flatten(),
         Stream.tap((cause) =>
-          shutdown(cause._tag === 'LiveStore.IntentionalShutdownCause' ? Exit.succeed(cause) : Exit.fail(cause)),
+          shutdown(cause._tag === 'IntentionalShutdownCause' ? Exit.succeed(cause) : Exit.fail(cause)),
         ),
         Stream.runDrain,
         Effect.interruptible,
@@ -179,7 +247,7 @@ const makeAdapterImpl = ({
       const lockStatus = yield* SubscriptionRef.make<LockStatus>('has-lock')
 
       const devtoolsOptions: WorkerSchema.LeaderWorkerInnerInitialMessage['devtools'] =
-        devtoolsEnabled && devtoolsOptionsInput !== undefined
+        devtoolsEnabled === true && devtoolsOptionsInput !== undefined
           ? {
               enabled: true,
               schemaPath:
@@ -204,10 +272,11 @@ const makeAdapterImpl = ({
               storage,
               ...omitUndefineds({
                 syncOptions: leaderThreadInput.sync,
-                syncPayload,
+                syncPayloadEncoded,
+                syncPayloadSchema,
                 testing,
               }),
-            }).pipe(UnexpectedError.mapToUnexpectedError)
+            }).pipe(UnknownError.mapToUnknownError)
           : yield* makeWorkerLeaderThread({
               shutdown,
               storeId,
@@ -218,7 +287,7 @@ const makeAdapterImpl = ({
               storage,
               devtools: devtoolsOptions,
               bootStatusQueue,
-              syncPayload,
+              syncPayloadEncoded,
             })
 
       syncInMemoryDb.import(initialSnapshot)
@@ -229,7 +298,7 @@ const makeAdapterImpl = ({
         sqliteDb: syncInMemoryDb,
         webmeshMode: 'proxy',
         connectWebmeshNode: Effect.fnUntraced(function* ({ webmeshNode }) {
-          if (devtoolsOptions.enabled) {
+          if (devtoolsOptions.enabled === true) {
             yield* Webmesh.connectViaWebSocket({
               node: webmeshNode,
               url: `ws://${devtoolsOptions.host}:${devtoolsOptions.port}`,
@@ -244,6 +313,7 @@ const makeAdapterImpl = ({
         isLeader: true,
         // Not really applicable for node as there is no "reload the app" concept
         registerBeforeUnload: (_onBeforeUnload) => () => {},
+        origin: undefined,
       })
 
       return clientSession
@@ -258,7 +328,7 @@ const resetNodePersistence = ({
 }: {
   storage: WorkerSchema.StorageType
   storeId: string
-}): Effect.Effect<void, UnexpectedError, FileSystem.FileSystem> => {
+}): Effect.Effect<void, UnknownError, FileSystem.FileSystem> => {
   if (storage.type !== 'fs') {
     return Effect.void
   }
@@ -268,13 +338,13 @@ const resetNodePersistence = ({
   return Effect.gen(function* () {
     const fs = yield* FileSystem.FileSystem
 
-    const directoryExists = yield* fs.exists(directory).pipe(UnexpectedError.mapToUnexpectedError)
+    const directoryExists = yield* fs.exists(directory).pipe(UnknownError.mapToUnknownError)
 
     if (directoryExists === false) {
       return
     }
 
-    yield* fs.remove(directory, { recursive: true }).pipe(UnexpectedError.mapToUnexpectedError)
+    yield* fs.remove(directory, { recursive: true }).pipe(UnknownError.mapToUnknownError)
   }).pipe(
     Effect.retry({ schedule: Schedule.exponentialBackoff10Sec }),
     Effect.withSpan('@livestore/adapter-node:resetPersistence', { attributes: { directory } }),
@@ -287,7 +357,8 @@ const makeLocalLeaderThread = ({
   schema,
   makeSqliteDb,
   syncOptions,
-  syncPayload,
+  syncPayloadEncoded,
+  syncPayloadSchema,
   storage,
   devtools,
   testing,
@@ -298,7 +369,8 @@ const makeLocalLeaderThread = ({
   makeSqliteDb: MakeSqliteDb
   syncOptions: SyncOptions | undefined
   storage: WorkerSchema.StorageType
-  syncPayload: Schema.JsonValue | undefined
+  syncPayloadEncoded: Schema.JsonValue | undefined
+  syncPayloadSchema: Schema.Schema<any>
   devtools: WorkerSchema.LeaderWorkerInnerInitialMessage['devtools']
   testing?: {
     overrides?: TestingOverrides
@@ -312,7 +384,8 @@ const makeLocalLeaderThread = ({
         schema,
         syncOptions,
         storage,
-        syncPayload,
+        syncPayloadEncoded,
+        syncPayloadSchema,
         devtools,
         makeSqliteDb,
         ...omitUndefineds({ testing: testing?.overrides }),
@@ -320,7 +393,8 @@ const makeLocalLeaderThread = ({
     )
 
     return yield* Effect.gen(function* () {
-      const { dbState, dbEventlog, syncProcessor, extraIncomingMessagesQueue, initialState } = yield* LeaderThreadCtx
+      const { dbState, dbEventlog, syncProcessor, extraIncomingMessagesQueue, initialState, networkStatus } =
+        yield* LeaderThreadCtx
 
       const initialLeaderHead = Eventlog.getClientHeadFromDb(dbEventlog)
 
@@ -330,15 +404,26 @@ const makeLocalLeaderThread = ({
             pull: ({ cursor }) => syncProcessor.pull({ cursor }),
             push: (batch) =>
               syncProcessor.push(
-                batch.map((item) => new LiveStoreEvent.EncodedWithMeta(item)),
+                batch.map((item) => new LiveStoreEvent.Client.EncodedWithMeta(item)),
                 { waitForProcessing: true },
               ),
+            stream: (options) =>
+              streamEventsWithSyncState({
+                dbEventlog,
+                syncState: syncProcessor.syncState,
+                options,
+              }),
+          },
+          initialState: {
+            leaderHead: initialLeaderHead,
+            migrationsReport: initialState.migrationsReport,
+            storageMode: 'persisted',
           },
-          initialState: { leaderHead: initialLeaderHead, migrationsReport: initialState.migrationsReport },
           export: Effect.sync(() => dbState.export()),
           getEventlogData: Effect.sync(() => dbEventlog.export()),
-          getSyncState: syncProcessor.syncState,
+          syncState: syncProcessor.syncState,
           sendDevtoolsMessage: (message) => extraIncomingMessagesQueue.offer(message),
+          networkStatus,
         },
         { ...omitUndefineds({ overrides: testing?.overrides?.clientSession?.leaderThreadProxy }) },
       )
@@ -359,10 +444,10 @@ const makeWorkerLeaderThread = ({
   storage,
   devtools,
   bootStatusQueue,
-  syncPayload,
+  syncPayloadEncoded,
   testing,
 }: {
-  shutdown: (cause: Exit.Exit<IntentionalShutdownCause, UnexpectedError | SyncError>) => Effect.Effect<void>
+  shutdown: (cause: Exit.Exit<IntentionalShutdownCause, UnknownError>) => Effect.Effect<void>
   storeId: string
   clientId: string
   sessionId: string
@@ -371,15 +456,15 @@ const makeWorkerLeaderThread = ({
   storage: WorkerSchema.StorageType
   devtools: WorkerSchema.LeaderWorkerInnerInitialMessage['devtools']
   bootStatusQueue: Queue.Queue<BootStatus>
-  syncPayload: Schema.JsonValue | undefined
+  syncPayloadEncoded: Schema.JsonValue | undefined
   testing?: {
     overrides?: TestingOverrides
   }
 }) =>
   Effect.gen(function* () {
     const nodeWorker = new WT.Worker(workerUrl, {
-      execArgv: process.env.DEBUG_WORKER ? ['--inspect --enable-source-maps'] : ['--enable-source-maps'],
-      argv: [Schema.encodeSync(WorkerSchema.WorkerArgv)({ storeId, clientId, sessionId, extraArgs: workerExtraArgs })],
+      execArgv: process.env.DEBUG_WORKER !== undefined ? ['--inspect --enable-source-maps'] : ['--enable-source-maps'],
+      argv: [yield* Schema.encode(WorkerSchema.WorkerArgv)({ storeId, clientId, sessionId, extraArgs: workerExtraArgs }).pipe(Effect.orDie)],
     })
     const nodeWorkerLayer = yield* Layer.build(PlatformNode.NodeWorker.layer(() => nodeWorker))
 
@@ -392,56 +477,39 @@ const makeWorkerLeaderThread = ({
           clientId,
           storage,
           devtools,
-          syncPayload,
+          syncPayloadEncoded,
         }),
     }).pipe(
       Effect.provide(nodeWorkerLayer),
-      UnexpectedError.mapToUnexpectedError,
+      UnknownError.mapToUnknownError,
       Effect.tapErrorCause((cause) => shutdown(Exit.failCause(cause))),
       Effect.withSpan('@livestore/adapter-node:adapter:setupLeaderThread'),
     )
 
-    const runInWorker = <TReq extends typeof WorkerSchema.LeaderWorkerInnerRequest.Type>(
-      req: TReq,
-    ): TReq extends Schema.WithResult<infer A, infer _I, infer _E, infer _EI, infer R>
-      ? Effect.Effect<A, UnexpectedError, R>
-      : never =>
-      (worker.executeEffect(req) as any).pipe(
+    const runInWorker = <A, I, E, EI, R>(
+      req: WorkerSchema.LeaderWorkerInnerRequest & Schema.WithResult<A, I, E, EI, R>,
+    ): Effect.Effect<A, E, R> =>
+      worker.executeEffect(req).pipe(
+        Effect.catchIf(isWorkerTransportError, (e) => Effect.die(e)),
         Effect.logWarnIfTakesLongerThan({
           label: `@livestore/adapter-node:client-session:runInWorker:${req._tag}`,
           duration: 2000,
         }),
         Effect.withSpan(`@livestore/adapter-node:client-session:runInWorker:${req._tag}`),
-        Effect.mapError((cause) =>
-          Schema.is(UnexpectedError)(cause)
-            ? cause
-            : ParseResult.isParseError(cause) || Schema.is(WorkerError.WorkerError)(cause)
-              ? new UnexpectedError({ cause })
-              : cause,
-        ),
-        Effect.catchAllDefect((cause) => new UnexpectedError({ cause })),
-      ) as any
-
-    const runInWorkerStream = <TReq extends typeof WorkerSchema.LeaderWorkerInnerRequest.Type>(
-      req: TReq,
-    ): TReq extends Schema.WithResult<infer A, infer _I, infer _E, infer _EI, infer R>
-      ? Stream.Stream<A, UnexpectedError, R>
-      : never =>
-      worker.execute(req as any).pipe(
-        Stream.mapError((cause) =>
-          Schema.is(UnexpectedError)(cause)
-            ? cause
-            : ParseResult.isParseError(cause) || Schema.is(WorkerError.WorkerError)(cause)
-              ? new UnexpectedError({ cause })
-              : cause,
-        ),
+      )
+
+    const runInWorkerStream = <A, I, E, EI, R>(
+      req: WorkerSchema.LeaderWorkerInnerRequest & Schema.WithResult<A, I, E, EI, R>,
+    ): Stream.Stream<A, E, R> =>
+      worker.execute(req).pipe(
+        Stream.refineOrDie((e) => isWorkerTransportError(e) === true ? Option.none() : Option.some(e)),
         Stream.withSpan(`@livestore/adapter-node:client-session:runInWorkerStream:${req._tag}`),
-      ) as any
+      )
 
     const bootStatusFiber = yield* runInWorkerStream(new WorkerSchema.LeaderWorkerInnerBootStatusStream()).pipe(
       Stream.tap((bootStatus) => Queue.offer(bootStatusQueue, bootStatus)),
       Stream.runDrain,
-      Effect.tapErrorCause((cause) => (Cause.isInterruptedOnly(cause) ? Effect.void : shutdown(Exit.failCause(cause)))),
+      Effect.tapErrorCause((cause) => (Cause.isInterruptedOnly(cause) === true ? Effect.void : shutdown(Exit.failCause(cause)))),
       Effect.interruptible,
       Effect.tapCauseLogPretty,
       Effect.forkScoped,
@@ -456,8 +524,7 @@ const makeWorkerLeaderThread = ({
     const initialLeaderHead = yield* runInWorker(new WorkerSchema.LeaderWorkerInnerGetLeaderHead())
 
     const bootResult = yield* runInWorker(new WorkerSchema.LeaderWorkerInnerGetRecreateSnapshot()).pipe(
-      Effect.timeout(10_000),
-      UnexpectedError.mapToUnexpectedError,
+      Effect.timeoutOrDie(10_000),
       Effect.withSpan('@livestore/adapter-node:client-session:export'),
     )
 
@@ -472,26 +539,36 @@ const makeWorkerLeaderThread = ({
                 attributes: { batchSize: batch.length },
               }),
             ),
+          stream: (options) =>
+            runInWorkerStream(new WorkerSchema.LeaderWorkerInnerStreamEvents(options)).pipe(
+              Stream.withSpan('@livestore/adapter-node:client-session:streamEvents'),
+              Stream.orDie,
+            ),
         },
         initialState: {
           leaderHead: initialLeaderHead,
           migrationsReport: bootResult.migrationsReport,
+          storageMode: 'persisted',
         },
         export: runInWorker(new WorkerSchema.LeaderWorkerInnerExport()).pipe(
-          Effect.timeout(10_000),
-          UnexpectedError.mapToUnexpectedError,
+          Effect.timeoutOrDie(10_000),
           Effect.withSpan('@livestore/adapter-node:client-session:export'),
         ),
         getEventlogData: Effect.dieMessage('Not implemented'),
-        getSyncState: runInWorker(new WorkerSchema.LeaderWorkerInnerGetLeaderSyncState()).pipe(
-          UnexpectedError.mapToUnexpectedError,
-          Effect.withSpan('@livestore/adapter-node:client-session:getLeaderSyncState'),
-        ),
+        syncState: Subscribable.make({
+          get: runInWorker(new WorkerSchema.LeaderWorkerInnerGetLeaderSyncState()).pipe(
+            Effect.withSpan('@livestore/adapter-node:client-session:getLeaderSyncState'),
+          ),
+          changes: runInWorkerStream(new WorkerSchema.LeaderWorkerInnerSyncStateStream()).pipe(Stream.orDie),
+        }),
         sendDevtoolsMessage: (message) =>
           runInWorker(new WorkerSchema.LeaderWorkerInnerExtraDevtoolsMessage({ message })).pipe(
-            UnexpectedError.mapToUnexpectedError,
             Effect.withSpan('@livestore/adapter-node:client-session:devtoolsMessageForLeader'),
           ),
+        networkStatus: Subscribable.make({
+          get: runInWorker(new WorkerSchema.LeaderWorkerInnerGetNetworkStatus()).pipe(Effect.orDie),
+          changes: runInWorkerStream(new WorkerSchema.LeaderWorkerInnerNetworkStatusStream()).pipe(Stream.orDie),
+        }),
       },
       {
         ...omitUndefineds({ overrides: testing?.overrides?.clientSession?.leaderThreadProxy }),

package/src/devtools/devtools-server.ts

@@ -20,6 +20,16 @@ import { makeMeshNode, makeWebSocketEdge } from '@livestore/webmesh'
 
 import { makeViteMiddleware } from './vite-dev-server.ts'
 
+/**
+ * Determines if a request URL should be routed to the Vite middleware.
+ * Includes LiveStore devtools paths and Vite internal paths like `/@fs/`, `/@vite/`, etc.
+ */
+const shouldRouteToVite = (url: string): boolean =>
+  url.startsWith('/_livestore') ||
+  url.startsWith('/@fs') ||
+  url.startsWith('/@vite') ||
+  url.startsWith('/@react-refresh')
+
 /**
  * Starts a devtools HTTP/WS server which serves ...
  * - the Devtools UI via Vite
@@ -39,11 +49,12 @@ export const startDevtoolsServer = ({
   Effect.gen(function* () {
     const viteMiddleware = yield* makeViteMiddleware({
       mode: { _tag: 'node', url: `http://${host}:${port}` },
-      schemaPath: isReadonlyArray(schemaPath)
-        ? schemaPath.map((schemaPath) => path.resolve(process.cwd(), schemaPath))
-        : path.resolve(process.cwd(), schemaPath),
+      schemaPath:
+        isReadonlyArray(schemaPath) === true
+          ? schemaPath.map((schemaPath) => path.resolve(process.cwd(), schemaPath))
+          : path.resolve(process.cwd(), schemaPath),
       viteConfig: (viteConfig) => {
-        if (LS_DEV) {
+        if (LS_DEV === true) {
           viteConfig.server ??= {}
           viteConfig.server.fs ??= {}
           viteConfig.server.fs.strict = false
@@ -63,7 +74,7 @@ export const startDevtoolsServer = ({
     const handler = Effect.gen(function* () {
       const req = yield* HttpServerRequest.HttpServerRequest
 
-      if (Headers.has(req.headers, 'upgrade')) {
+      if (Headers.has(req.headers, 'upgrade') === true) {
         // yield* Effect.logDebug(`WS Relay ${relayNodeName}: WS upgrade request ${req.url}`)
 
         const socket = yield* req.upgrade
@@ -81,7 +92,7 @@ export const startDevtoolsServer = ({
               .addEdge({ target: from, edgeChannel: webChannel, replaceIfExists: true })
               .pipe(Effect.acquireRelease(() => node.removeEdge(from).pipe(Effect.orDie)))
 
-            if (LS_DEV) {
+            if (LS_DEV === true) {
               yield* Effect.log(`WS Relay ${relayNodeName}: added edge from '${from}'`)
               yield* Effect.addFinalizerLog(`WS Relay ${relayNodeName}: removed edge from '${from}'`)
             }
@@ -96,7 +107,7 @@ export const startDevtoolsServer = ({
       } else {
         if (req.url === '/' || req.url === '') {
           return HttpServerResponse.redirect('/_livestore/node')
-        } else if (req.url.startsWith('/_livestore')) {
+        } else if (shouldRouteToVite(req.url) === true) {
           // Here we're delegating to the Vite middleware
 
           // TODO replace this once @effect/platform-node supports Node HTTP middlewares
@@ -114,9 +125,10 @@ export const startDevtoolsServer = ({
       return HttpServerResponse.text('Not found')
     }).pipe(Effect.tapCauseLogPretty, Effect.interruptible)
 
-    const sessionSuffix = clientSessionInfo
-      ? `/${clientSessionInfo.storeId}/${clientSessionInfo.clientId}/${clientSessionInfo.sessionId}/${clientSessionInfo.schemaAlias}`
-      : '?autoconnect'
+    const sessionSuffix =
+      clientSessionInfo !== undefined
+        ? `/${clientSessionInfo.storeId}/${clientSessionInfo.clientId}/${clientSessionInfo.sessionId}/${clientSessionInfo.schemaAlias}`
+        : '?autoconnect'
 
     // Use `localhost` instead of `0.0.0.0` as it doesn't have the `navigator.locks` web adapter limitation (https://share.cleanshot.com/nHBnmk6S)
     const maybeLocalhost = host === '0.0.0.0' ? 'localhost' : host

package/src/devtools/mod.ts

@@ -1,3 +1,3 @@
 export { startDevtoolsServer } from './devtools-server.ts'
 export type { ViteDevtoolsOptions } from './vite-dev-server.ts'
-export { makeViteMiddleware } from './vite-dev-server.ts'
+export { DevtoolsViteNotInstalledError, makeViteMiddleware } from './vite-dev-server.ts'

package/src/devtools/vite-dev-server.ts

@@ -1,12 +1,44 @@
 import path from 'node:path'
 
+import type * as Vite from 'vite'
+
 import type { Devtools } from '@livestore/common'
-import { UnexpectedError } from '@livestore/common'
-import { livestoreDevtoolsPlugin } from '@livestore/devtools-vite'
+import { UnknownError } from '@livestore/common'
 import { isReadonlyArray } from '@livestore/utils'
-import { Effect } from '@livestore/utils/effect'
+import { Effect, Schema } from '@livestore/utils/effect'
 import { getFreePort } from '@livestore/utils/node'
-import * as Vite from 'vite'
+
+/**
+ * Error thrown when @livestore/devtools-vite is not installed.
+ * This is a peer dependency that must be installed separately.
+ */
+export class DevtoolsViteNotInstalledError extends Schema.TaggedError<DevtoolsViteNotInstalledError>(
+  '~@livestore/adapter-node/DevtoolsViteNotInstalledError',
+)('DevtoolsViteNotInstalledError', {
+  cause: Schema.Defect,
+}) {
+  override get message(): string {
+    return (
+      `@livestore/devtools-vite is required for devtools but not installed. ` +
+      `Install it with: pnpm add @livestore/devtools-vite@<version>. ` +
+      `Make sure to use the same version as @livestore/adapter-node.`
+    )
+  }
+}
+
+/** Error thrown when vite is not installed for the devtools server path. */
+export class ViteNotInstalledError extends Schema.TaggedError<ViteNotInstalledError>(
+  '~@livestore/adapter-node/ViteNotInstalledError',
+)('ViteNotInstalledError', {
+  cause: Schema.Defect,
+}) {
+  override get message(): string {
+    return (
+      `vite is required for @livestore/adapter-node/devtools but not installed. ` +
+      `Install it with: pnpm add -D vite@<version>.`
+    )
+  }
+}
 
 export type ViteDevtoolsOptions = {
   viteConfig?: (config: Vite.UserConfig) => Vite.UserConfig
@@ -26,11 +58,16 @@ export type ViteDevtoolsOptions = {
 }
 
 // NOTE this is currently also used in @livestore/devtools-expo
-export const makeViteMiddleware = (options: ViteDevtoolsOptions): Effect.Effect<Vite.ViteDevServer, UnexpectedError> =>
+export const makeViteMiddleware = (
+  options: ViteDevtoolsOptions,
+): Effect.Effect<Vite.ViteDevServer, DevtoolsViteNotInstalledError | ViteNotInstalledError | UnknownError> =>
   Effect.gen(function* () {
+    const { livestoreDevtoolsPlugin } = yield* importDevtoolsVite()
+    const Vite = yield* importVite()
+
     const cwd = process.cwd()
 
-    const hmrPort = yield* getFreePort.pipe(UnexpectedError.mapToUnexpectedError)
+    const hmrPort = yield* getFreePort.pipe(UnknownError.mapToUnknownError)
 
     const defaultViteConfig = Vite.defineConfig({
       server: {
@@ -39,13 +76,13 @@ export const makeViteMiddleware = (options: ViteDevtoolsOptions): Effect.Effect<
           port: hmrPort,
         },
         // Relaxing fs access for monorepo setup
-        fs: { strict: process.env.LS_DEV ? false : true },
+        fs: { strict: process.env.LS_DEV !== undefined ? false : true },
       },
       appType: 'spa',
       base: '/_livestore/',
       plugins: [
         livestoreDevtoolsPlugin({
-          schemaPath: isReadonlyArray(options.schemaPath)
+          schemaPath: isReadonlyArray(options.schemaPath) === true
             ? options.schemaPath.map((schemaPath) => path.resolve(cwd, schemaPath))
             : path.resolve(cwd, options.schemaPath),
           mode: options.mode,
@@ -58,9 +95,24 @@ export const makeViteMiddleware = (options: ViteDevtoolsOptions): Effect.Effect<
 
     const viteConfig = options.viteConfig?.(defaultViteConfig) ?? defaultViteConfig
 
-    const viteServer = yield* Effect.promise(() => Vite.createServer(viteConfig)).pipe(
-      UnexpectedError.mapToUnexpectedError,
-    )
+    const viteServer = yield* Effect.promise(() => Vite.createServer(viteConfig)).pipe(UnknownError.mapToUnknownError)
 
     return viteServer
   }).pipe(Effect.withSpan('@livestore/adapter-node:devtools:makeViteServer'))
+
+/**
+ * Dynamically imports @livestore/devtools-vite.
+ * This package is a peer dependency and may not be installed.
+ */
+const importDevtoolsVite = () =>
+  Effect.tryPromise({
+    try: () => import('@livestore/devtools-vite'),
+    catch: (cause) => new DevtoolsViteNotInstalledError({ cause }),
+  })
+
+/** Dynamically imports vite for the devtools-only server path. */
+const importVite = () =>
+  Effect.tryPromise({
+    try: () => import('vite'),
+    catch: (cause) => new ViteNotInstalledError({ cause }),
+  })