import PackageManagers from "../../../../components/PackageManagers.astro"; export const devDeps = "@alchemy.run/frontend-frameworks"; Railway.Website.Octane deploys an OctaneJS
fullstack app to Railway. Octane wraps Vite, so the resource is
deliberately thin: it runs your project's own vite build — Octane's
plugin builds the client bundle and the self-contained SSR server
bundle, and the Node deploy target's finishing pass wraps its fetch
handler as a Node HTTP program. The server plus client assets run on
one Railway.Service from a container image. The live URL is the generated
https://{name}.up.railway.app. No Dockerfile, no build command to
run.
Install
The build integration is not bundled with alchemy. Install
@alchemy.run/frontend-frameworks; the resource loads the package's
/octane and /octane/node exports from your project at deploy
time. It is only used at build time, so a dev dependency is enough:
Configure Octane
Keep native compiler and route settings in octane.config.ts, without
an adapter:
// octane.config.ts
import { defineConfig, RenderRoute } from "@octanejs/vite-plugin";
export default defineConfig({
router: {
routes: [new RenderRoute({ path: "/", entry: ["App", "/src/App.tsx"] })],
},
}); Railway.Website.Octane selects hosting and automatically wraps Octane's
default native Node output as an HTTP server. The legacy Node marker
adapter remains optional for existing projects.
Vite plugins like Tailwind go in vite.config.ts next to it,
alongside the Octane plugin:
// vite.config.ts
import { octane } from "@octanejs/vite-plugin";
import tailwindcss from "@tailwindcss/vite";
import { defineConfig } from "vite";
export default defineConfig({
plugins: [octane(), tailwindcss()],
}); Declare the Website
Declare the site as a module-level const (rather than inline in the Stack):
// alchemy.run.ts
import * as Railway from "@alchemy.run/railway";
export const Website = Railway.Website.Octane("Website"); Omit project and Alchemy creates a Railway.Project under the
site's namespace. Pass an existing Project to put the site in it:
export const Site = Railway.Project("Site");
export const Website = Railway.Website.Octane("Website", {
project: Site,
}); Add it to the Stack
Yield the site from your Stack and return its URL:
// alchemy.run.ts
import * as Alchemy from "alchemy";
import * as Effect from "effect/Effect";
export default Alchemy.Stack(
"MyOctaneSite",
{
providers: Railway.providers(),
state: Alchemy.localState(),
},
Effect.gen(function* () {
const site = yield* Website;
return { url: site.url };
}),
); On deploy, url is the Service's https://{name}.up.railway.app.
The resolved site also exposes service and project (both
undefined under alchemy dev).
Add environment variables
Process environment is configured under env — plain strings, or
Redacted values. They are copied onto process.env before the
build and onto the Service at deploy time:
// alchemy.run.ts
export const Website = Railway.Website.Octane("Website", {
+ env: {
+ GREETING: "Hello from alchemy",
+ API_BASE: "https://api.example.com",
+ },
}); The same values are injected into the dev server's process
environment under alchemy dev, so server code reads them in both
modes.
Read the environment in server code
Octane's server runs in Node on the Service, so middleware and
ServerRoute handlers read the environment from process.env:
// octane.config.ts
new ServerRoute({
path: "/api/greeting",
methods: ["GET"],
handler: async () => {
return Response.json({ greeting: process.env.GREETING ?? "hello" });
},
}); Asset routing
Octane's intended setup is asset-first with SSR on miss: exact files
in dist/client are served by the Node process without invoking the
Octane handler, and every miss streams from Octane SSR. That is the
default — there is nothing to configure. The Service healthcheck is
GET /health on port 3000.
Local dev
bun alchemy dev alchemy dev runs Octane's own Vite dev server — the plugin's
in-process SSR middleware serves rendering, server routes, and RPC
with full HMR. site.url is the local address and no Railway
resources are created (service and project are undefined;
Wrap the site in Alchemy.remote() to deploy
the real infrastructure even during dev.
Custom domain
const site = yield* Railway.Website.Octane("Web", {
domain: "app.example.com",
}); Alchemy attaches a Railway.CustomDomain (targetPort 3000) and
url becomes https://{domain}. Point DNS at Railway's
verification records — see
custom domains.