Documentation

CLI

@kynetra/fx-cli is the official scaffolding tool for Kynetra FX. A single command — kynetra new <name> — generates a fully wired project for your target runtime, including a working route handler, middleware stack, runtime adapter, and all configuration files needed to develop and deploy immediately.

Overview#

Rather than copying boilerplate by hand or reading through configuration docs before writing your first route, @kynetra/fx-cli gets you to a running application in under a minute. The generated project is not a starter template with example pages and placeholder comments — it is a minimal, production-shaped scaffold with the correct dependencies, types, and configuration for the runtime you chose.

Generates package.json with the correct runtime adapter dependency.
Writes src/index.ts with a working createFX() app, three standard middleware items, and a root route.
Emits wrangler.toml for Cloudflare Workers projects.
Writes tsconfig.json tuned to the target runtime.
Creates .gitignore covering node_modules, .wrangler, and build output.
Supports four runtimes: cloudflare (default), node, bun, deno.

Installation and quick start#

@kynetra/fx-cli is designed to be used with npx — no global installation required. The package is self-contained and always runs the latest version.

Run kynetra new

Pass the project name as the first argument. The CLI creates a directory with that name under the current working directory and writes all project files into it.

npx @kynetra/fx-cli new my-api

Enter the project directory

cd my-api

Install dependencies

npm install

Start the development server

For Cloudflare projects, use wrangler dev. For Node, Bun, and Deno projects, use the runtime's native runner.

# Cloudflare (default)
npx wrangler dev
 
# Node
node --experimental-strip-types src/index.ts
 
# Bun
bun run src/index.ts
 
# Deno
deno run --allow-net src/index.ts

Tip

The Cloudflare runtime is the default because it is the primary deployment target for Kynetra FX. If you are building for a different runtime, pass --runtime at scaffold time rather than editing the generated files afterwards — the adapter import and configuration differ across runtimes.

Command reference#

kynetra new

Creates a new project directory and writes all scaffold files into it. The only required argument is the project name.

npx @kynetra/fx-cli new <name> [--runtime cloudflare|node|bun|deno]

Full examples for each supported runtime:

# Create a Cloudflare Workers project (default runtime)
npx @kynetra/fx-cli new my-api
 
# Create a Node.js project
npx @kynetra/fx-cli new my-server --runtime node
 
# Create a Bun project
npx @kynetra/fx-cli new my-bun-app --runtime bun
 
# Create a Deno project
npx @kynetra/fx-cli new my-deno-app --runtime deno

name — the project name. Used as the directory name, the namefield in package.json, and the Worker name in wrangler.toml. Must be a valid npm package name (lowercase, hyphens allowed).
--runtime — target runtime. Determines which adapter package is installed and which entry file template is emitted. Defaults to cloudflare.

What gets scaffolded#

Cloudflare Workers (default)

The Cloudflare scaffold includes wrangler.toml in addition to the standard files, and the entry file exports the app through the cloudflare() adapter. Three middleware items — requestId, logger, and cors — are wired by default so the Worker is observable and CORS-ready from the first request.

src/index.ts

import { createFX, cors, logger, requestId } from '@kynetra/fx'
import { cloudflare } from '@kynetra/fx-cloudflare'
 
const app = createFX({ runtime: 'cloudflare' })
 
app.use(requestId())
app.use(logger())
app.use(cors())
 
app.get('/', (ctx) => ctx.json({ hello: 'world' }))
 
return cloudflare(app)

wrangler.toml

name = "my-api"
main = "src/index.ts"
compatibility_date = "2024-01-01"

Node.js

The Node scaffold uses the @kynetra/fx-node adapter. The serve()call starts an HTTP server on the port specified by the PORT environment variable, falling back to 3000.

src/index.ts

import { createFX, cors, logger, requestId } from '@kynetra/fx'
import { serve } from '@kynetra/fx-node'
 
const app = createFX({ runtime: 'node' })
 
app.use(requestId())
app.use(logger())
app.use(cors())
 
app.get('/', (ctx) => ctx.json({ hello: 'world' }))
 
serve(app, { port: parseInt(process.env.PORT ?? '3000') })

Bun

The Bun scaffold uses the @kynetra/fx-bun adapter. Bun's native HTTP server is used under the hood — no additional configuration is needed.

src/index.ts

import { createFX, cors, logger, requestId } from '@kynetra/fx'
import { serve } from '@kynetra/fx-bun'
 
const app = createFX({ runtime: 'bun' })
 
app.use(requestId())
app.use(logger())
app.use(cors())
 
app.get('/', (ctx) => ctx.json({ hello: 'world' }))
 
serve(app, { port: parseInt(process.env.PORT ?? '3000') })

Deno

The Deno scaffold uses the @kynetra/fx-deno adapter and is compatible with Deno Deploy. The generated file imports from npm specifiers, which Deno resolves automatically when --allow-net is passed.

src/index.ts

import { createFX, cors, logger, requestId } from '@kynetra/fx'
import { serve } from '@kynetra/fx-deno'
 
const app = createFX({ runtime: 'deno' })
 
app.use(requestId())
app.use(logger())
app.use(cors())
 
app.get('/', (ctx) => ctx.json({ hello: 'world' }))
 
serve(app, { port: parseInt(Deno.env.get('PORT') ?? '3000') })

Common files across all runtimes

Every scaffold — regardless of runtime — includes the following files in addition to the runtime-specific src/index.ts:

package.json — project metadata with @kynetra/fx and the runtime adapter as dependencies, plus typescript as a dev dependency.
tsconfig.json — TypeScript configuration with strict: true,moduleResolution: "bundler", and target: "ES2022".
.gitignore — covers node_modules/, .wrangler/,dist/, and *.env.

Warning

The CLI creates the project directory itself. If a directory with the given name already exists in the current working directory, the CLI will exit with an error rather than overwrite existing files. Rename or remove the existing directory first.

Library API#

All CLI behaviour is exposed as a programmatic library. You can use these functions to integrate scaffolding into your own tooling, monorepo setup scripts, or custom generators.

Name	Type	Description
scaffoldProject	function	Creates all project files at dir/name. Accepts { name, dir, runtime? }. Returns a promise that resolves when all files are written.
parseArgs	function	Parses a process.argv-style string array. Returns { command, name, runtime } — command is always "new" for the current version.
run	function	Top-level entry point. Parses argv, validates arguments, and calls scaffoldProject. Equivalent to running the CLI directly.

Programmatic usage#

Import from @kynetra/fx-cli to scaffold projects from your own scripts. This is useful in monorepo tooling, test fixture setup, or CI pipelines that need to generate fresh projects.

scripts/scaffold.ts

import { scaffoldProject, run } from '@kynetra/fx-cli'
 
// Option 1: call scaffoldProject directly
await scaffoldProject({
  name: 'my-project',
  dir: process.cwd(),
  runtime: 'node',
})
 
// Option 2: run the CLI programmatically (parses args the same way the binary does)
await run(['new', 'my-project', '--runtime', 'node'])

Using scaffoldProject in a monorepo

In a monorepo workflow, you might scaffold new services into a services/subdirectory automatically. Pass dir as the absolute path to that directory and name as the service name.

scripts/new-service.ts

import { scaffoldProject } from '@kynetra/fx-cli'
import path from 'node:path'
 
const name = process.argv[2]
if (!name) {
  console.error('Usage: tsx scripts/new-service.ts <name>')
  process.exit(1)
}
 
await scaffoldProject({
  name,
  dir: path.join(process.cwd(), 'services'),
  runtime: 'cloudflare',
})
 
console.log(`Created services/${name}`)
console.log('Next: cd services/' + name + ' && npm install && npx wrangler dev')

Note

See Cloudflare Workers for deployment steps after scaffolding a Cloudflare project, Node.js and Bun / Deno for runtime-specific configuration, and self-hosting for containerised and bare-metal deployments.

PreviousLanguages NextPlayground