Backan Builder

The backan builder library allows you to build multiple things. Among others:

• Executables / binaries
• client library
• JSON schema file
• TypeScript definitions file
• Markdown documentation

🔑 Installation

npm

npm install @backan/builder

pnpm

pnpm i @backan/builder

yarn

yarn add @backan/builder

bun

bun add @backan/builder

Build binaries

Package your Node.js project into an executable that can be run even on devices without Node.js installed.

The construction of the binary allows compilation on arm and x64 architecture.

If you compile on an x64 system it will not create the binaries for arm, but if you compile on arm it will create the binaries for both architectures.

This library works thanks to ncc, pkg and esbuild, which facilitate this process.

Using Backan Builder is simple and will work in most cases, but that may not be the case. If so, we recommend using other alternatives such as ncc or pkg.

📈 usage

js

import {build} from '@backan/builder'

await build( {
 input  : 'src/server.js', // JS or TS file
 name   : 'app-name', // default is input filename
} )

bash

backan-builder --input=src/server.js --name=app-name

⚙️ Configuration

All of these options are available with the backan-builder command by adding the suffix -- and followed by an = and its value.

type BuilderParams = {
 /**
  * The app server input file.
  *
  * The input can be provided without an extension. 
  * If the extension is omitted, the system will automatically look for the following extensions: `.ts`, `.js`, `.mjs`, `.mts`.
  */
 input: string, 
 /**
  * Binary name.
  */
 name?: string,
 /**
  * Directory for the output build.
  *
  * @default './build'
  */
 outDir?: string, 
 /**
  * Build only binary for your current OS.
  *
  * @default false
  */
 onlyOs?: boolean
 /**
  * The build type Result [all|cjs|bin].
  *
  * @default 'all'
  */
 type?: 'all'|'cjs'|'bin'
 
}

Build JSON | Types schema

import {buildSchema} from '@backan/builder'
import {app} from './app.js' 

buildSchema( {
 app    : app,
 output : 'openapi-schema.json',
} )

Parameters

export type BuilderSchemaParams = {
	/**
	 * The instance of the Backan application used to generate the OpenAPI schema.
	 */
	app: App<Env>,
	/**
	 * The path where the resulting `json` file will be saved.
	 */
	output: string 
	/**
	 * Generate dts file.
	 *
	 * @default true
	 */
	dts?: boolean
}

Build Markdown documentation

import {buildMD} from '@backan/builder'
import {app} from './app.js' 

buildMD( {
 app    : app,
 output : 'api-documentation.md',
} )

Parameters

type BuilderMDParams = {
	/**
	 * The instance of the Backan application used to generate the OpenAPI schema.
	 */
	app: App<Env>,
	/**
	 * The path where the resulting `Markdown` file will be saved.
	 */
	output: string 
}

Create client

Create a client for your backan API and make your frontend app able to access your API easily and with type. To achieve this, backan makes use of the openapi-featch library.

import { createClient } from '@backan/builder'
import type { paths }   from './openapi.d.ts' // Generate with buildSchema

const client = createClient<paths>( {
	baseUrl : 'http://localhost:1312/',
} )

export {client}

Example of call

import {client} from './client.js'
const response = await client.GET( '/random/child', {
	params : {
		query : {
			value : 'myValue', 
		}, 
	},
} )

console.log( response )