A Node or Bun server

A host like a VPS, a container, or Railway runs one process for you. You give it a folder and one command that starts it, and that folder shouldn't carry your src, your dev dependencies, or the seedcord CLI.

seedcord build writes that folder. Point build.start at the file that starts your bot. seedcord.config.ts covers root, instance, and the other keys.

import { defineConfig } from 'seedcord';

export default defineConfig({
    root: './src',
    instance: './bot.ts',
    build: { start: './index.ts' }
});

import seedcord from './bot';

await seedcord.start();

index.ts only starts the bot that bot.ts exports, and a bot from pnpm create seedcord already has both files. With build.start set, the build writes dist/index.mjs, which runs index.ts. Without build.start, the build writes a bot that other code imports, which a package and an embedded bot both use.

pnpm run build

seedcord v0.21.5  build

  ✔︎ read config    197ms
  ✔︎ load bot       152ms
  ✔︎ type check     698ms  tsconfig.json
  ✔︎ bundle          36ms

  11 modules, 0 listed files, 8.7 kB → dist/index.mjs

  run      node dist/index.mjs
  compile  bun build --compile dist/index.mjs --outfile my-bot

Each ✔︎ line is one step. The three that do the work:

• load bot imports your instance file and constructs the bot, the same way seedcord dev does. An env value your config reads at construction has to exist in CI too, or the build stops here.
• type check runs tsc --noEmit against the tsconfig.json beside seedcord.config.ts, from your project's own typescript. build.tsconfig points it at another file.
• bundle runs Vite and writes dist, with index.mjs as the entry, one .js file for each of your modules, and a source map beside each. The code stays unminified. Every code file under root builds, whether or not your bot imports it.

The last two lines print the commands that start what it built. The run line uses the runtime the CLI ran on, so bun --bun run build prints bun dist/index.mjs. The compile line takes the binary's name from your package.json, without the scope, so @acme/my-bot builds to my-bot.

Vite deletes everything in outDir before it writes, so a file from a source you deleted can't linger in dist. Before that happens, the build checks the folder. It goes ahead if outDir doesn't exist, is empty, or holds an index.mjs that an earlier seedcord build wrote. Anything else stops it:

[3117] build.outDir is dist, which already contains other files. seedcord build empties outDir before it writes. Point it at an empty folder, or delete what is in it.

That's CliBuildOutDirNotEmpty.

The scaffold's start script runs the build with node's --enable-source-maps flag:

node --enable-source-maps dist/index.mjs

The printed run line leaves the flag out, so add it yourself. Without it, a stack trace points at lines in dist. With it, node reads the source maps the build wrote and points at your .ts lines.

To run it on a host, copy the whole dist folder there, along with package.json and your production dependencies, since dist imports packages like @seedcord/gateway from node_modules.

A host that only got dist and package.json has no seedcord.config.ts, which changes where the bot looks for .env. A built bot's .env files has both cases.

bun build --compile turns the build into a single executable that carries the Bun runtime and every dependency inside it. The host then needs no node, no Bun, and no node_modules:

bun build --compile dist/index.mjs --outfile my-bot
./my-bot

Bun stores the bot's files inside the executable, under a virtual /$bunfs folder. The bot then never finds seedcord.config.ts on disk, even on the machine that built it, so it reads .env from the folder you start the binary in. Put a .env beside it, or set the variables on the host. The data files you list under files are inside the binary already.

@seedcord/tsconfig sets "types": ["node"], which leaves Bun.* untyped. If your bot calls Bun's APIs, install @types/bun and add it to your tsconfig:

pnpm add -D @types/bun

{
    "extends": "@seedcord/tsconfig/node",
    "compilerOptions": {
        "types": ["node", "bun", "vite/client"]
    }
}

A bot that calls Bun.* only runs on Bun after that, so use these APIs only if you've already picked Bun for production.

Most hosting platforms call an http endpoint to check that your process is still alive. A gateway bot opens a small server that answers /health on port 6967 once startup finishes, after every plugin's ready(), and closes it when the bot shuts down. It does this under seedcord dev too.

import { Seedcord } from '@seedcord/gateway';
import { GatewayIntentBits } from 'discord.js';

export default new Seedcord({
    bot: {
        clientOptions: { intents: [GatewayIntentBits.Guilds] },
        interactions: { path: './handlers' },
        commands: { path: './commands' },
        events: { path: null }
    },
    subscribers: { path: null },
    healthCheck: { port: 8080, path: '/healthz' }
});

This bot answers /healthz on port 8080. All three keys are optional. port defaults to 6967, path to /health, and host to every network interface. healthCheck: true and leaving the key out both give you those defaults. healthCheck: false turns the server off.

Change port or path if your host expects its health check somewhere else. Set host if the server should only listen inside a container network. Turn it off if nothing calls it or port 6967 is already taken on the machine.

The build prints the error under the step that failed. Problems in seedcord.config.ts itself, like an outDir that holds root, come first, all at once. Config mistakes lists them.

Run the build with --verbose to see the resolved config and the full stack of any seedcord error.