import * as NodePath from "node:path";
import * as Effect from "effect/Effect";
import * as FileSystem from "effect/FileSystem";
import * as Layer from "effect/Layer";
import * as Path from "effect/Path";
import * as Schedule from "effect/Schedule";
import * as Semaphore from "effect/Semaphore";
import * as FrameworkCore from "../core/index.ts";
import {
Framework,
FrameworkError,
type DeployTarget,
type DeployTargetInput,
} from "../core/index.ts";
import {
findPresetConflict,
hasForeignNitroPlugin,
markInjectedPlugins,
pluginConflictMessage,
presetConflictMessage,
resolveNitroConfig,
resolveNitroOutputDirs,
type NitroConfigSlice,
} from "./UserConfig.ts";
/**
* The structural slice of the project's `vite` module this package drives.
* Typed structurally so the package carries no dependency on vite — the
* *project's* install is always the one loaded.
*
* `createBuilder` (not `build`) is the entry point: SolidStart declares a
* `builder.buildApp` that builds the client and SSR environments (and, with
* the nitro plugin, runs nitro over the SSR bundle). Vite's legacy `build()`
* only builds the default environment, so it would silently produce the
* client bundle and nothing else.
*/
export interface SolidStartViteModule {
readonly version?: string;
readonly createBuilder: (config: Record<string, unknown>) => Promise<SolidStartViteBuilder>;
readonly createServer: (config: Record<string, unknown>) => Promise<SolidStartViteDevServer>;
}
/** The structural slice of a vite builder this package reads. */
export interface SolidStartViteBuilder {
readonly buildApp: () => Promise<unknown>;
}
/** The structural slice of a Vite dev server this package reads. */
export interface SolidStartViteDevServer {
readonly listen: () => Promise<unknown>;
readonly close: () => Promise<void>;
readonly resolvedUrls?: { readonly local: ReadonlyArray<string> } | null | undefined;
}
/**
* The structural slice of the project's `@solidjs/vite-plugin-nitro-2`
* module this package drives.
*/
export interface SolidStartNitroPluginModule {
readonly nitroV2Plugin: (nitroConfig?: Record<string, unknown>) => unknown;
}
/** Inputs the framework passes when consulting the target's nitro hook. */
export interface SolidStartNitroContext {
/** Absolute project root. */
readonly root: string;
}
/**
* The configuration this package assembles from {@link SolidStartOptions}
* and hands to a deploy-target factory. The target treats it as its
* `DeployTarget.config`; the framework half never inspects a resolved
* target's config.
*/
export interface SolidStartTargetConfig {
/**
* Nitro options forwarded into the appended `nitroV2Plugin(...)` instance
* (prerendering, route rules, storage, ...). `preset` is owned by the
* deploy target and may not be set here.
*
* Carried on the target config so wholesale targets that re-run the
* framework in a child process (the AWS target) can reconstruct the
* framework with the same options.
*/
readonly nitro?: Record<string, unknown> | undefined;
}
/**
* A deploy target for SolidStart: the generic `DeployTarget` seams plus the
* nitro hooks the SolidStart build needs — the deployment preset to build
* with, and a last-word pass over the nitro config the integration hands to
* the SolidStart nitro plugin.
*/
export interface SolidStartTarget extends DeployTarget<SolidStartTargetConfig> {
/** The nitro deployment preset this target builds with (e.g. `"aws-lambda"`). */
readonly nitroPreset: string;
/**
* Last-word mutation of the nitro config, run after the caller's `nitro`
* overrides and after the preset is enforced (e.g. the AWS target forces
* `awsLambda.streaming`).
*/
readonly configureNitro?:
| ((nitroConfig: NitroConfigSlice, context: SolidStartNitroContext) => void)
| undefined;
}
/**
* How a deploy target is passed to this package: a `SolidStartTarget` value,
* a factory `(config) => SolidStartTarget`, or a module specifier resolved
* from the *project's* `node_modules`.
*/
export type SolidStartTargetInput = DeployTargetInput<SolidStartTarget, SolidStartTargetConfig>;
/**
* The default deploy target: this package's own AWS Lambda target module,
* loaded from the project's dependency tree. (Cloudflare deploys SolidStart
* through its native Vite integration — `Cloudflare.Website.Vite` — so no
* Cloudflare target exists here.)
*/
export const DEFAULT_TARGET_SPECIFIER = "@alchemy.run/frontend-frameworks/solidstart/aws";
/** The specifier the project's SolidStart nitro plugin is loaded from. */
export const NITRO_PLUGIN_SPECIFIER = "@solidjs/vite-plugin-nitro-2";
export interface SolidStartOptions {
/**
* Project root (the directory containing `vite.config.*`).
* @default process.cwd()
*/
readonly root?: string | undefined;
/**
* The deploy target the build is produced for. Accepts a target value, a
* `(config) => target` factory, or a module specifier string.
* @default "@alchemy.run/frontend-frameworks/solidstart/aws"
*/
readonly target?: SolidStartTargetInput | undefined;
/**
* Nitro options forwarded into the appended `nitroV2Plugin(...)` instance.
* `preset` is owned by the deploy target and may not be set here.
*/
readonly nitro?: Record<string, unknown> | undefined;
readonly dev?:
| {
/** Default dev-server port (overridden by `FrameworkDevOptions.port`). */
readonly port?: number | undefined;
}
| undefined;
}
const fail = (message: string, cause?: unknown) =>
new FrameworkError({ framework: "solidstart", message, cause });
/**
* Serializes cwd swaps across concurrent dev-server starts in one process (the
* same discipline as the Waku framework's lock). Without it two interleaved
* acquire/release pairs leave the process cwd pointing at the wrong project:
* A chdir(/orig -> /a); B captures previous=/a, chdir(/b); A restores /orig;
* B restores /a.
*/
const cwdLock = Semaphore.makeUnsafe(1);
/**
* Run `effect` with the process working directory set to the project root,
* restoring it afterwards. A no-op (and lock-free) when the cwd already is the
* root — the case for the isolated build child process.
*
* SolidStart 2's `solidStart()` plugin resolves the app root, the route
* directory, and the `~` alias from `process.cwd()` at config-load time —
* not from vite's `root` — so it only finds the app when the process is IN
* the project. Production builds are already isolated in a child process
* whose cwd IS the root (see `aws.ts`), which makes this a no-op there; the
* dev server runs in the caller's process (alchemy's dev sidecar), so the
* cwd is aligned only across the window in which vite evaluates the config
* module, and restored immediately after.
*
* Consequence, upstream and unavoidable while the plugin keys off the cwd:
* one process can host the dev server of ONE SolidStart project at a time.
*/
const inProjectCwd = <A, E, R>(
root: string,
effect: Effect.Effect<A, E, R>,
): Effect.Effect<A, E | FrameworkError, R> =>
Effect.flatMap(
Effect.sync(() => process.cwd() === NodePath.resolve(root)),
(isRoot) =>
isRoot
? effect
: Semaphore.withPermits(
cwdLock,
1,
)(
Effect.acquireUseRelease(
Effect.try({
try: () => {
const previous = process.cwd();
process.chdir(root);
return previous;
},
catch: (error) => fail(`Failed to enter the project directory ${root}`, error),
}),
() => effect,
(previous) =>
Effect.sync(() => {
try {
if (process.cwd() !== previous) {
process.chdir(previous);
}
} catch {
// restoring the cwd is best-effort
}
}),
),
),
);
/**
* Build the `Framework` service implementation for a SolidStart project.
*
* - `build` resolves the deploy target, then either delegates wholesale
* (`target.build`) or drives the PROJECT's own Vite install
* programmatically: `createBuilder({ root, plugins: [nitroV2Plugin(...)] })`
* followed by `buildApp()`. The project's `vite.config.*` loads natively
* (its `solidStart()` plugin is untouched); the integration APPENDS a
* `nitroV2Plugin` instance — loaded from the project's own
* `node_modules` — carrying the deploy target's preset. Inline plugins are
* merged after the config file's, so the appended instance's
* `builder.buildApp` gets the last word. The `BuildOutput` is read from
* nitro's `.output`: `serverModules` entry-first from `.output/server`,
* `clientDirectory` = `.output/public` (prerendered pages included).
* - `dev` runs the project's own Vite dev server (SolidStart's dev-server
* plugin serves SSR through it, with native HMR), scoped — closing the
* Scope closes the server. Nitro plays no part in dev.
*
* This module is target-agnostic: everything AWS-specific lives in
* `@alchemy.run/frontend-frameworks/solidstart/aws`.
*/
export const make: (
options?: SolidStartOptions,
) => Effect.Effect<Framework["Service"], never, FileSystem.FileSystem | Path.Path> =
Effect.fnUntraced(function* (options?: SolidStartOptions) {
const fs = yield* FileSystem.FileSystem;
const path = yield* Path.Path;
const baseRoot = options?.root ?? (yield* Effect.sync(() => process.cwd()));
const targetConfig: SolidStartTargetConfig = { nitro: options?.nitro };
const resolveTarget = (root: string) =>
FrameworkCore.resolveDeployTarget<SolidStartTarget, SolidStartTargetConfig>(
root,
options?.target ?? DEFAULT_TARGET_SPECIFIER,
targetConfig,
).pipe(Effect.mapError((error) => fail(error.message, error.cause)));
const requireNitroPreset = (target: SolidStartTarget) =>
typeof target.nitroPreset === "string" && target.nitroPreset.length > 0
? Effect.succeed(target)
: Effect.fail(
fail(
`The resolved "${target.platform}" deploy target does not declare the nitro ` +
"preset hook (`nitroPreset`) and has no wholesale `build`",
),
);
const loadVite = (root: string) =>
FrameworkCore.loadProjectModule<SolidStartViteModule>(root, "vite").pipe(
Effect.mapError((error) => fail("Failed to load the project's Vite install", error.cause)),
);
const loadNitroPlugin = (root: string) =>
FrameworkCore.loadProjectModule<SolidStartNitroPluginModule>(
root,
NITRO_PLUGIN_SPECIFIER,
).pipe(
Effect.mapError((error) =>
fail(
`Failed to load the project's "${NITRO_PLUGIN_SPECIFIER}" — install it alongside ` +
"`@solidjs/start`; it is the server half of a SolidStart build",
error.cause,
),
),
);
const build: Framework["Service"]["build"] = Effect.fn(function* (buildOptions) {
const root = buildOptions?.root ?? baseRoot;
const target = yield* resolveTarget(root);
const targetContext = {
root,
framework: "solidstart",
env: buildOptions?.env,
};
// Wholesale build takeover (the AWS target uses this seam to run the
// build in a disposable child process — vite.config.* executes user
// plugins that must not touch the engine process).
if (target.build !== undefined) {
return yield* target.build(targetContext).pipe(
Effect.mapError((error) => fail(error.message, error.cause)),
Effect.provideService(FileSystem.FileSystem, fs),
Effect.provideService(Path.Path, path),
);
}
yield* requireNitroPreset(target);
// Conflict policy: the deploy target owns the preset, so a foreign one
// is rejected with an actionable error instead of being replaced — a
// build for a different preset would never be deployed.
const conflict = findPresetConflict(options?.nitro, target.nitroPreset);
if (conflict !== undefined) {
return yield* fail(presetConflictMessage(conflict, target.nitroPreset));
}
const vite = yield* loadVite(root);
const nitro = yield* loadNitroPlugin(root);
const nitroConfig = resolveNitroConfig({
preset: target.nitroPreset,
rootDir: root,
nitro: options?.nitro,
configure: (config) => target.configureNitro?.(config, { root }),
});
// Detected inside vite's own config resolution (the project's
// `vite.config.*` has been loaded and merged by then), reported as a
// FrameworkError once the build promise rejects.
const detected = { conflict: false };
const plugins = markInjectedPlugins([
{
name: "alchemy:solidstart-nitro-conflict",
enforce: "pre" as const,
config: (config: { readonly plugins?: unknown }) => {
if (hasForeignNitroPlugin(config.plugins)) {
detected.conflict = true;
throw new Error(pluginConflictMessage());
}
return null;
},
},
nitro.nitroV2Plugin(nitroConfig),
]);
yield* inProjectCwd(
root,
Effect.tryPromise({
try: async () => {
const builder = await vite.createBuilder({
root,
// Fixture clones have no local node_modules, so Vite would
// otherwise share `packages/alchemy/node_modules/.vite` with
// every other website test. Vocs writes shiki there; the
// SolidStart nitro graph then emits 11MB of grammars and
// SSR GET `/` hangs. Pin the cache under this project.
cacheDir: path.join(root, "node_modules", ".vite"),
// Warn-level: rolldown-vite's native progress reporter writes
// straight to the fd, corrupting hosting-process reporters
// that can only intercept JS-level writers.
logLevel: "warn",
plugins,
});
return await builder.buildApp();
},
catch: (error) =>
detected.conflict
? fail(pluginConflictMessage(), error)
: fail("Failed to build", error),
}),
);
const dirs = resolveNitroOutputDirs(nitroConfig, root, (...segments) =>
path.resolve(...segments),
);
const output = yield* readNitroOutput(dirs).pipe(
Effect.provideService(FileSystem.FileSystem, fs),
);
// The finishing-pass seam (none needed for the aws-lambda preset — the
// output is already a self-contained Node deployment unit — but the
// contract is honored for targets that do post-process).
return yield* FrameworkCore.applyDeployTargetFinish(target, output, {
...targetContext,
entry: path.join(dirs.serverDir, "index.mjs"),
}).pipe(
Effect.mapError((error) => fail(error.message, error.cause)),
Effect.provideService(FileSystem.FileSystem, fs),
Effect.provideService(Path.Path, path),
);
});
const devInProcess: Framework["Service"]["dev"] = Effect.fn(function* (devOptions) {
const root = devOptions?.root ?? baseRoot;
const vite = yield* loadVite(root);
// `port: 0` (true OS-assigned) on Vite >= 8.2.1, probed ephemeral port
// on older Vite — see `resolveViteDevPort`.
const port = yield* FrameworkCore.resolveViteDevPort(
vite.version,
devOptions?.port ?? options?.dev?.port,
);
const host = devOptions?.host;
const server = yield* Effect.acquireRelease(
inProjectCwd(
root,
Effect.tryPromise({
try: async () => {
const server = await vite.createServer({
root,
cacheDir: path.join(root, "node_modules", ".vite"),
logLevel: "warn",
server: {
port,
...(host !== undefined ? { host } : undefined),
},
});
await server.listen();
return server;
},
catch: (error) => fail("Failed to start the SolidStart dev server", error),
}),
),
(server) =>
Effect.promise(async () => {
try {
await server.close();
} catch {
// teardown is best-effort
}
}),
);
const resolved = server.resolvedUrls?.local[0];
if (resolved === undefined) {
return yield* fail("Could not determine the dev server URL");
}
// Vite reports its local URL with a trailing slash. SolidStart runs with
// `appType: "custom"`, so its router sees the raw pathname and a caller
// that appends a path (`${url}/about`) would request `//about` and get a
// 404. Hand back an origin that concatenates correctly.
const url = resolved.endsWith("/") ? resolved.slice(0, -1) : resolved;
// Bounded readiness probe: any HTTP response counts (vite serves
// lazily; we only need the listener to answer).
yield* Effect.tryPromise({
try: async () => {
const response = await fetch(url, { redirect: "manual" });
await response.arrayBuffer().catch(() => {});
},
catch: (error) => fail("The dev server did not become reachable", error),
}).pipe(Effect.retry({ schedule: Schedule.spaced("250 millis"), times: 40 }));
return { url };
});
// SolidStart's `solidStart()` plugin resolves the app from `process.cwd()`
// at config-load time, so its startup needs `cwd === root`. That must not
// happen in a process hosting other sites (the alchemy dev sidecar) — run
// the dev server in a dedicated child whose cwd IS the root instead (see
// core/DevChild.ts). Inside that child (or when the options cannot cross
// the process boundary, e.g. a deploy-target VALUE from the e2e harness)
// the in-process path runs directly.
const dev: Framework["Service"]["dev"] = (devOptions) => {
const root = devOptions?.root ?? baseRoot;
const port = devOptions?.port ?? options?.dev?.port;
if (FrameworkCore.isInsideDevChild() || !FrameworkCore.isJsonSerializable(options)) {
return devInProcess(devOptions);
}
return FrameworkCore.runDevChild({
framework: "solidstart",
module: "@alchemy.run/frontend-frameworks/solidstart",
callerUrl: import.meta.url,
rootDir: root,
makeOptions: { ...options, root },
devOptions: {
root,
...(port !== undefined ? { port } : {}),
...(devOptions?.host !== undefined ? { host: devOptions.host } : {}),
},
});
};
return Framework.of({ build, dev });
});
/** The nitro server entry's module name within the `BuildOutput` (POSIX). */
export const SERVER_ENTRY_NAME = "server/index.mjs";
/** The resolved nitro output directories. */
export interface NitroOutputDirs {
/** Root output directory (`.output`). */
readonly dir: string;
/** Server bundle directory (`.output/server`). */
readonly serverDir: string;
/** Static assets directory (`.output/public`, prerendered pages included). */
readonly publicDir: string;
}
/**
* Map nitro's on-disk `.output` onto the `BuildOutput` contract:
* `serverModules` entry-first from the server directory (POSIX names,
* sha256-hashed), `clientDirectory` = the public directory. Nitro's output
* is self-contained (externals are copied into `.output/server/node_modules`),
* so there are no external workspace roots to watch.
*/
export const readNitroOutput = (
dirs: NitroOutputDirs,
): Effect.Effect<FrameworkCore.BuildOutput, FrameworkError, FileSystem.FileSystem> =>
Effect.gen(function* () {
const modules = yield* FrameworkCore.readServerModulesFromDisk({
directory: dirs.serverDir,
prefix: "server",
}).pipe(Effect.mapError((error) => fail(error.message, error.cause)));
if (modules.length === 0) {
return yield* fail(`The SolidStart build produced no server modules in ${dirs.serverDir}`);
}
const serverModules = FrameworkCore.sortServerModules(modules, SERVER_ENTRY_NAME);
if (serverModules[0]?.name !== SERVER_ENTRY_NAME) {
return yield* fail(
`The SolidStart build produced no "${SERVER_ENTRY_NAME}" entry in ${dirs.serverDir}`,
);
}
return {
distDirectory: dirs.dir,
clientDirectory: dirs.publicDir,
serverModules,
externalWorkspaces: new Set<string>(),
} satisfies FrameworkCore.BuildOutput;
});
/**
* A `Layer` providing framework-core's `Framework` service for a SolidStart
* project — the fully-typed entrypoint for `e2e.config.ts` and alchemy's
* `AWS.Website.SolidStart` composite.
*/
export const layer = (
options?: SolidStartOptions,
): Layer.Layer<Framework, never, FileSystem.FileSystem | Path.Path> =>
Layer.effect(Framework, make(options));