Main Blocks

The main: block in a .dox file orchestrates commands that are executed when you run paradox start.

Syntax

main:
  paradox:
    generate:
      --typescript
  paradox-node:
    --port: 3000
    --crud: Pet
    --title: "My App"

The main: section is a YAML-like block at the top level of a .dox file. Commands run in order from top to bottom.

Commands

paradox

Invoke the Paradox CLI to generate code:

main:
  paradox:
    generate:
      --typescript

Multiple generation targets can be invoked separately:

main:
  paradox:
    generate: "--haskell"
  paradox:
    generate: "--rust"

paradox-express

Generate an Express.js API server with custom URI routes:

main:
  paradox:
    generate:
      --typescript
  paradox-express:
    --title: "My API"
    --uri: createUser
    --uri: getUser
    --uri: listUsers
    --uri: healthCheck

The --uri flag references URI constants defined in your .dox file. Each becomes an Express route handler.

paradox-node

Generate a full Node.js server with CRUD, authentication, permissions, and an admin UI:

main:
  paradox:
    generate:
      --typescript
  paradox-node:
    --port: 3000
    --crud: Pet
    --account: User
    --permissions: permissions
    --title: "D's Pets"
    --footer: "D (c) 2025"
    --extra: "extra.ts"
Flag Description

--port

Server port number

--crud

Type to generate CRUD routes for

--account

Type to use for user accounts

--permissions

Name of the permissions matrix

--title

Application title for the admin UI

--footer

Footer text for the admin UI

--extra

Path to an extra TypeScript file to include

--uris

URI constants to expose as API endpoints

npx

Run an npm package command:

main:
  npx:
    vite:
      build

Sub-commands and arguments are nested as YAML-like blocks.

ln

Create symbolic links:

main:
  ln: "-sfn ../../../.dox/playground.rs frontend/src/generated/playground.rs"

This is useful for symlinking generated output into a frontend or other project directory.

Full Example

A complete main.dox from the example Pet API:

main:
  paradox:
    generate:
      --typescript
  paradox-express:
    --title: "D's Pets"
    --uris: healthCheck
    --uris: petStats
    --uris: petRoutes
  paradox-node:
    --port: 3000
    --crud: Pet
    --account: User
    --permissions: permissions
    --title: "D's Pets"
    --footer: "D (c) 2025"
    --extra: "extra.ts"
  npx:
    vite:
      build

This single block generates TypeScript types, sets up both an Express API and a Node admin server, and builds the frontend — all from paradox start.

Arguments

Arguments in main: blocks can be:

  • Primitive arguments: string values like "3000" or "extra.ts"

  • Flag arguments: CLI flags like --typescript, --crud

  • Type arguments: references to Paradox types like Pet, User

  • Name arguments: references to constants like permissions, healthCheck

  • Nested commands: sub-commands with their own arguments (e.g., generate: under paradox:)

Running

Execute the main: block with:

paradox start --path .

This processes the .dox files, runs the commands in the main: block in order, and keeps the process alive for server commands.

paradox-node Server

When using paradox-node, the generated server includes:

  • Express.js routes for every --crud type with CRUD operations

  • Validation middleware using the generated validators

  • An admin UI with configurable title and footer

  • Permission checks based on the --permissions matrix

  • Account system using the --account type

  • Custom API endpoints from --uris constants

  • Extra TypeScript via --extra for custom logic

The server configuration is driven by the node.dox module (import node), which defines:

  • Manifest — server title, author, footer

  • CRUDRoutes — auto-generated REST endpoints

  • Settings — port, CRUD targets, permissions

See Also