API Reference

Complete API documentation for OpenCode's programmatic interface.

JavaScript API

Use OpenCode programmatically in Node.js:

import { build, createServer, defineConfig } from 'opencode';

// Build for production
await build({
  root: process.cwd(),
  build: {
    outDir: 'dist'
  }
});

// Start dev server
const server = await createServer({
  root: process.cwd(),
  server: {
    port: 3000
  }
});

await server.listen();

build()

Build your project for production.

Signature

async function build(config?: InlineConfig): Promise<BuildResult>

Options

interface InlineConfig {
  root?: string;          // Project root directory
  base?: string;          // Base public path
  mode?: string;          // 'development' | 'production'
  configFile?: string;    // Path to config file
  logLevel?: 'info' | 'warn' | 'error' | 'silent';
  build?: BuildOptions;
  plugins?: Plugin[];
}

Example

import { build } from 'opencode';

const result = await build({
  root: './src',
  build: {
    outDir: '../dist',
    minify: true,
    sourcemap: true,
    rollupOptions: {
      input: {
        main: './src/main.ts',
        admin: './src/admin.ts'
      }
    }
  }
});

console.log('Build complete:', result.output);

createServer()

Create a development server instance.

Signature

async function createServer(config?: InlineConfig): Promise<DevServer>

DevServer Methods

Method	Description
listen(port?)	Start the server
close()	Stop the server
restart()	Restart the server
printUrls()	Print server URLs

Example

import { createServer } from 'opencode';

const server = await createServer({
  server: {
    port: 3000,
    open: true,
    cors: true
  }
});

await server.listen();
server.printUrls();

// Later: graceful shutdown
process.on('SIGTERM', async () => {
  await server.close();
  process.exit(0);
});

defineConfig()

Helper for defining configuration with TypeScript support.

Signature

function defineConfig(config: UserConfig): UserConfig;
function defineConfig(config: (env: ConfigEnv) => UserConfig): (env: ConfigEnv) => UserConfig;

Example

import { defineConfig } from 'opencode';

export default defineConfig(({ command, mode }) => {
  if (command === 'serve') {
    return {
      // dev specific config
    };
  } else {
    return {
      // build specific config
    };
  }
});

resolveConfig()

Resolve and merge configuration from all sources.

import { resolveConfig } from 'opencode';

const config = await resolveConfig(
  { /* inline config */ },
  'build',  // command
  'production'  // mode
);

console.log(config.build.outDir);

transformWithEsbuild()

Transform code using esbuild.

import { transformWithEsbuild } from 'opencode';

const result = await transformWithEsbuild(
  code,
  'file.tsx',
  {
    loader: 'tsx',
    target: 'es2020'
  }
);

console.log(result.code);

Plugin API

Create plugins with these hooks:

interface Plugin {
  name: string;
  enforce?: 'pre' | 'post';
  apply?: 'build' | 'serve';
  
  // Config hooks
  config?(config, env): UserConfig | null | void;
  configResolved?(config): void;
  
  // Build hooks
  buildStart?(options): void;
  resolveId?(source, importer): ResolveIdResult;
  load?(id): LoadResult;
  transform?(code, id): TransformResult;
  buildEnd?(error?): void;
  
  // Dev server hooks
  configureServer?(server): void;
  handleHotUpdate?(ctx): HmrContext;
}

Type Definitions

Full TypeScript definitions are included:

// Import types
import type {
  UserConfig,
  Plugin,
  BuildOptions,
  ServerOptions,
  ResolvedConfig
} from 'opencode';

// Use in your code
const config: UserConfig = {
  build: {
    target: 'es2020'
  }
};