sailfork / t3code-github / .repos/ alchemy-effect/ website/ src/ content/ docs/ railway/ compute/ projects.mdx

A Railway.Project is a workspace-scoped namespace. It owns environments and services. Names are unique per workspace.

Create a Project

Alchemy generates a unique name unless you pass one.

const site = yield* Railway.Project("Site");

url is https://railway.com/project/{projectId}. A production environment is created with the project — do not recreate it as an Environment. environmentId is that primary environment.

Nothing answers on the public internet until a Service is deployed. The Service gets its own *.up.railway.app hostname.

:::note Prefer omitting name in tests and CI so names stay unique and reclaimable. :::

A stable name

Pass name when you need a stable project name.

const site = yield* Railway.Project("Site", {
  name: "my-site",
});

Changing name later updates the project in place.

Description

description is optional and updates in place.

const site = yield* Railway.Project("Site", {
  description: "production web app",
});

Workspace

Workspace defaults to the current token (me.workspace ?? me.workspaces[0]). Pass workspaceId to pin it.

const site = yield* Railway.Project("Site", {
  name: "my-site",
+  workspaceId: "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
});

:::caution[Changing workspaceId replaces the Project] The Project is created in the new workspace. The old Project is deleted. :::

Default environment name

defaultEnvironmentName is create-only. Railway's default is production. Extra environments (staging) are a separate Environment resource.

const site = yield* Railway.Project("Site", {
  defaultEnvironmentName: "production",
});

Module-scope declarations

Declare the Project once. Pass it into every child.

// src/project.ts
import * as Railway from "@alchemy.run/railway";

export const Site = Railway.Project("Site");

Resource-valued props accept the resource or an Effect producing it. Do not unwrap it just to pass it along.

Destroy

alchemy destroy deletes children, then the Project.

Where next

The tutorial deploys a Project from an empty directory. Services run in the Project. Environments add staging. The Project reference lists every prop. Example: railway-project is a Project plus an image Service.