okhp3-replit-multi-artifact

OverKill Hill P³ · overkillhill.com · github.com/OKHP3

Each of the following rules has caused a multi-turn debugging session in a real project. None of them is in the artifact creation walkthrough. This skill exists because knowing the rule before you hit the failure is worth four turns of debugging.

Scope

Artifact kinds and their skills

Never call createArtifact twice for the same slug. If artifacts/<slug>/ already exists, the call fails.

Rule 1: BASE_URL prefix — the most common silent failure

Every route and API call in an artifact must prepend import.meta.env.BASE_URL (Vite artifacts) or the equivalent base path helper.

Why. Replit uses path-based routing. Each artifact is mounted at a unique preview path (e.g. /my-app). A root-relative URL like /api/users escapes the artifact's path prefix and hits the wrong route — or a 404. The failure is silent: the URL looks correct in code, the app loads, but API calls return unexpected responses.

Correct:

// artifacts/my-app/src/api/client.ts
const BASE = import.meta.env.BASE_URL; // includes trailing slash
const res = await fetch(`${BASE}api/users`);

Incorrect (do not do):

const res = await fetch('/api/users'); // root-relative — escapes the artifact's mount path

For Expo apps: use the getApiUrl() helper from the Expo scaffold, which reads the dev domain environment variable.

Rule 2: PORT env var — never hard-code a port

Every artifact's dev server must read the port from the PORT environment variable, not from a hard-coded number.

Why. The system assigns a unique port per artifact to avoid collisions. A hard-coded port in Vite config (e.g. server: { port: 3000 }) will either conflict with another artifact or be wrong for the proxy routing. The result is a blank preview pane with no error.

Correct Vite config:

// vite.config.ts
export default defineConfig({
  server: {
    port: parseInt(process.env.PORT || '5000', 10),
    host: '0.0.0.0',
    allowedHosts: true  // required — preview is proxied through an iframe
  }
});

Correct Express config:

// server.ts
const port = parseInt(process.env.PORT || '3001', 10);
app.listen(port, '0.0.0.0');

allowedHosts: true is required for Vite. The preview is a proxied iframe; requests come from a different origin. Without this, Vite rejects them with a 403 and the preview is blank.

Rule 3: Managed workflow naming — do not replace with configureWorkflow

Every registered artifact service already has a managed workflow:

artifacts/<slug>: <service-name>

Examples:

• artifacts/api-server: API Server
• artifacts/chai-chasers: web
• artifacts/mockup-sandbox: Component Preview Server

Never call configureWorkflow to create a replacement workflow for an artifact service. Managed workflows inject service configuration including PORT, BASE_PATH, and proxy routing. A replacement workflow omits this configuration and creates a conflicting preview path.

To start or restart an artifact service, use the WorkflowsRestart tool directly:

// Correct — use WorkflowsRestart tool
// name: "artifacts/chai-chasers: web"

Or in CodeExecution:

await restartWorkflow({ workflowName: "artifacts/chai-chasers: web" });

Only use configureWorkflow for long-running processes that are not represented by a registered artifact service.

Rule 4: pnpm catalog drift — off-catalog pins break plugin typechecks

The workspace root package.json is an implicit pnpm workspace member. Off-catalog pins in any package's package.json — for packages like vite or @types/node — create duplicate store instances.

Symptom: Vite plugin typecheck passes in isolation but fails when the workspace resolves dependencies. TypeScript sees two copies of the same package with incompatible types.

Fix:

1. Check the root pnpm-workspace.yaml for a catalog: block.
2. Any package pinned with an exact version (e.g. "vite": "5.4.19") that also appears in the catalog must use "vite": "catalog:" instead.
3. Run pnpm install from the workspace root after changing pins.
4. If a specific version is required (e.g. a CVE override), document it explicitly — do not silently pin.

Why the root matters. pnpm treats the root package.json as a workspace member. Off-catalog pins there affect every other member's dependency resolution.

Rule 5: Cross-artifact shared libraries via workspace:*

To share code between artifacts (e.g. a shared utility library or API client):

1. Create the library as a package in lib/<name>/ or artifacts/<name>/ with its own package.json declaring "name": "@workspace/<name>".
2. In the consuming artifact's package.json, add:

   { "dependencies": { "@workspace/<name>": "workspace:*" } }

3. Run pnpm install from the workspace root so the symlink is created.
4. Import from the package name, not a relative path:

   import { myUtil } from "@workspace/my-lib";

Why workspace:* and not a relative path. Relative paths across package boundaries break TypeScript project references and Vite's module resolution. workspace:* lets pnpm manage the symlink correctly.

After adding a shared dependency: restart the artifact's workflow so Vite picks up the new symlink.

Blank-preview debug checklist

When the preview pane is blank or shows a connection error, work through this list in order:

If all seven are clean and the preview is still blank, read the debug-workflow-ports-issues skill.

Artifact registration summary

When creating a new artifact, createArtifact() handles:

• Creating artifacts/<slug>/ with scaffold files
• Writing artifact.toml
• Allocating a service port
• Registering the managed workflow

After createArtifact() returns, read the artifact kind's bootstrap skill (see the table above) before writing any code. The bootstrap skill tells you what to build and in what order.

About

Built from retrospective analysis of the Glee-fully Chai Chasers Designathon project at overkillhill.com. By Jamie Hill · OverKill Hill P³ · github.com/OKHP3 MIT License — free to use, fork, and adapt. A nod to the source is appreciated.