Code Generation

Configuration for generating TypeScript/JavaScript client code for NpgsqlRest endpoints.

Overview

{
  "NpgsqlRest": {
    "ClientCodeGen": {
      "Enabled": false,
      "FilePath": null,
      "FileOverwrite": true,
      "IncludeHost": true,
      "CustomHost": null,
      "CommentHeader": "Simple",
      "CommentHeaderIncludeComments": true,
      "BySchema": true,
      "IncludeStatusCode": true,
      "CreateSeparateTypeFile": true,
      "ImportBaseUrlFrom": null,
      "ImportParseQueryFrom": null,
      "IncludeParseUrlParam": false,
      "IncludeParseRequestParam": false,
      "HeaderLines": ["// autogenerated at {0}", ""],
      "SkipRoutineNames": [],
      "SkipFunctionNames": [],
      "SkipPaths": [],
      "SkipSchemas": [],
      "DefaultJsonType": "string",
      "UseRoutineNameInsteadOfEndpoint": false,
      "ExportUrls": false,
      "SkipTypes": false,
      "UniqueModels": false,
      "XsrfTokenHeaderName": null,
      "ExportEventSources": true,
      "CustomImports": [],
      "CustomHeaders": {},
      "IncludeSchemaInNames": true,
      "ErrorExpression": "await response.json()",
      "ErrorType": "{status: number; title: string; detail?: string | null} | undefined"
    }
  }
}

General Settings

Setting	Type	Default	Description
Enabled	bool	false	Enable client code generation.
FilePath	string	null	Output file path. Use {0} for schema name when BySchema is true. null to skip.
FileOverwrite	bool	true	Overwrite existing files.
BySchema	bool	true	Create separate files per PostgreSQL schema.
IncludeSchemaInNames	bool	true	Include schema name in generated type names to avoid collisions.

Host Configuration

Setting	Type	Default	Description
IncludeHost	bool	true	Include current host in URL prefix.
CustomHost	string	null	Custom host prefix for URLs.

Comment Headers

Setting	Type	Default	Description
CommentHeader	string	"Simple"	Comment header style: "None", "Simple", or "Full".
CommentHeaderIncludeComments	bool	true	Include routine comments in header.

Comment Header Styles

Style	Description
None	No comment header.
Simple	Add routine name, parameters, and return values (default).
Full	Add entire routine code as comment header.

Response Options

Setting	Type	Default	Description
IncludeStatusCode	bool	true	Include status code in response: {status: response.status, response: model}.
ErrorExpression	string	"await response.json()"	Expression to parse error responses. Only used when IncludeStatusCode is true.
ErrorType	string	(see below)	TypeScript type for error responses. Only used when IncludeStatusCode is true.

Default ErrorType: "{status: number; title: string; detail?: string | null} | undefined"

These options allow customization of error handling in generated code. Void functions and procedures also return the error object when IncludeStatusCode is true.

Type Generation

Setting	Type	Default	Description
CreateSeparateTypeFile	bool	true	Create separate {name}Types.d.ts file for global types.
DefaultJsonType	string	"string"	Default TypeScript type for JSON types.
SkipTypes	bool	false	Skip type generation for pure JavaScript output (changes .ts to .js).
UniqueModels	bool	false	Merge models with same fields/types into one (reduces generated models).

Import Configuration

Setting	Type	Default	Description
ImportBaseUrlFrom	string	null	Module to import baseUrl constant from.
ImportParseQueryFrom	string	null	Module to import parseQuery function from.
CustomImports	array	[]	Custom import statements (full expressions).

Function Parameters

Setting	Type	Default	Description
IncludeParseUrlParam	bool	false	Include parseUrl: (url: string) => string parameter.
IncludeParseRequestParam	bool	false	Include parseRequest: (request: RequestInit) => RequestInit parameter.

Skip Options

Setting	Type	Default	Description
SkipRoutineNames	array	[]	Routine names to skip (without schema).
SkipFunctionNames	array	[]	Generated function names to skip (without schema).
SkipPaths	array	[]	URL paths to skip.
SkipSchemas	array	[]	Schema names to skip.

Export Options

Setting	Type	Default	Description
ExportUrls	bool	false	Export URLs as constants.
ExportEventSources	bool	true	Export EventSource create functions for streaming events.
UseRoutineNameInsteadOfEndpoint	bool	false	Use routine name instead of endpoint name for functions.

Headers and Security

Setting	Type	Default	Description
CustomHeaders	object	{}	Custom headers added to each request.
XsrfTokenHeaderName	string	null	XSRF token header name for anti-forgery (used in upload FORM POSTs).

File Headers

Setting	Type	Default	Description
HeaderLines	array	["// autogenerated at {0}", ""]	Header lines for generated files. {0} = timestamp.

Path Parameters Support

When endpoints use path parameters (e.g., /products/{id}), TsClient automatically generates template literal URLs in the generated TypeScript code:

// Generated function for endpoint: GET /products/{pId}
export async function getProduct(request: { pId: number }) {
    const response = await fetch(`${baseUrl}/products/${request.pId}`, {
        method: "GET",
        headers: { "Content-Type": "application/json" }
    });
    return { status: response.status, response: await response.json() };
}

The parseQuery helper function is only included in generated files when there are actual query string parameters. Endpoints with only path parameters will not include this helper.

Example Configurations

Basic TypeScript Generation

{
  "NpgsqlRest": {
    "ClientCodeGen": {
      "Enabled": true,
      "FilePath": "./src/api/{0}Api.ts",
      "BySchema": true,
      "IncludeStatusCode": true,
      "CreateSeparateTypeFile": true
    }
  }
}

Single JavaScript File

{
  "NpgsqlRest": {
    "ClientCodeGen": {
      "Enabled": true,
      "FilePath": "./src/api/client.js",
      "BySchema": false,
      "SkipTypes": true,
      "IncludeSchemaInNames": false
    }
  }
}

Production Configuration

{
  "NpgsqlRest": {
    "ClientCodeGen": {
      "Enabled": true,
      "FilePath": "./client/src/api/{0}Api.ts",
      "FileOverwrite": true,
      "IncludeHost": false,
      "CustomHost": null,
      "CommentHeader": "Simple",
      "CommentHeaderIncludeComments": true,
      "BySchema": true,
      "IncludeStatusCode": true,
      "CreateSeparateTypeFile": true,
      "ImportBaseUrlFrom": "./config",
      "SkipSchemas": ["internal", "pg_catalog"],
      "UniqueModels": true,
      "ExportUrls": true,
      "ExportEventSources": true,
      "CustomHeaders": {
        "X-Client-Version": "\"1.0.0\""
      },
      "HeaderLines": [
        "// Auto-generated API client",
        "// Do not edit manually",
        ""
      ]
    }
  }
}

With Custom Imports and Parse Functions

{
  "NpgsqlRest": {
    "ClientCodeGen": {
      "Enabled": true,
      "FilePath": "./src/api/{0}Api.ts",
      "ImportBaseUrlFrom": "@/config",
      "ImportParseQueryFrom": "@/utils/query",
      "IncludeParseUrlParam": true,
      "IncludeParseRequestParam": true,
      "CustomImports": [
        "import { handleError } from '@/utils/errors';"
      ]
    }
  }
}

Related

• Comment Annotations Guide - How annotations work
• Configuration Guide - How configuration works

Next Steps

• HTTP Files - Configure HTTP file generation
• OpenAPI - Configure OpenAPI specification generation
• NpgsqlRest Options - Configure general NpgsqlRest settings