@backan/builder
Version:
Backan library for building executables, client libraries, JSON schema files, TypeScript definitions, and Markdown documentation.
337 lines (255 loc) ā¢ 12.6 kB
Markdown
<!-- PIGEONPOSSE START HEADER -->
[](https://backan.pigeonposse.com/)
[](https://pigeonposse.com)
[](https://pigeonposse.com?popup=about)
[](https://pigeonposse.com/?popup=donate)
[](https://github.com/pigeonposse)
[](https://twitter.com/pigeonposse_)
[](https://www.instagram.com/pigeon.posse/)
[](https://medium.com/@pigeonposse)
[](/LICENSE)
[](https://www.npmjs.com/package/backan)
[**BACKAN**](https://backan.pigeonposse.com/) Create endpoints with type validations and OpenApi documentation, safely and quickly.
<!-- PIGEONPOSSE END HEADER -->
> This package contains **_BACKAN_** Builder library
<!-- PIGEONPOSSE START DOCS -->
The backan builder library allows you to build multiple things. Among others:
- [**Executables / binaries**](
- [**client library**](
- [**JSON schema file**](
- [**TypeScript definitions file**](
- [**Markdown documentation**](
```bash [npm]
npm install @backan/builder
```
```bash [pnpm]
pnpm i @backan/builder
```
```bash [yarn]
yarn add @backan/builder
```
```bash [bun]
bun add @backan/builder
```
[](https://www.npmjs.com/package/@backan/builder)
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](https://github.com/vercel/ncc), [pkg](https://github.com/yao-pkg/pkg) and [esbuild](https://esbuild.github.io), 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](https://github.com/vercel/ncc) or [pkg](https://github.com/yao-pkg/pkg).
```js twoslash
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
```
All of these options are available with the `backan-builder` command by adding the suffix `--` and followed by an `=` and its value.
```ts
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'
}
```
```js twoslash
// @filename: app.js
import { App } from 'backan';
const app = new App( {
version : '1.0.0',
title : 'BACKAN Example app',
})
export {app}
// ---cut---
import {buildSchema} from '@backan/builder'
import {app} from './app.js'
buildSchema( {
app : app,
output : 'openapi-schema.json',
} )
```
```ts
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
}
```
```js twoslash
// @filename: app.js
import { App } from 'backan';
const app = new App( {
version : '1.0.0',
title : 'BACKAN Example app',
})
export {app}
// ---cut---
import {buildMD} from '@backan/builder'
import {app} from './app.js'
buildMD( {
app : app,
output : 'api-documentation.md',
} )
```
```ts
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 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`](https://openapi-ts.dev/openapi-fetch/) library.
```ts twoslash
// @noErrors
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}
```
```ts twoslash
// @filename: client.js
import { createClient } from '@backan/builder'
// @noErrors
import type { paths } from './openapi.d.ts' // Generate with buildSchema
const client = createClient<paths>( {
baseUrl : 'http://localhost:1312/',
} )
export {client}
// ---cut---
import {client} from './client.js'
const response = await client.GET( '/random/child', {
params : {
query : {
value : 'myValue',
},
},
} )
console.log( response )
```
<!-- PIGEONPOSSE END DOCS -->
<!-- PIGEONPOSSE START INDEX -->
- [Documentation](https://backan.pigeonposse.com/)
- š [Library](https://backan.pigeonposse.com/guide/core)
- š [Create (setup)]( https://backan.pigeonposse.com/guide/create )
- šļø [Server]( https://backan.pigeonposse.com/guide/server )
- š¦ [Builder]( https://backan.pigeonposse.com/guide/builder )
- [Installation](https://backan.pigeonposse.com/guide/core/#installation)
<!-- PIGEONPOSSE END INDEX -->
<!-- PIGEONPOSSE START ORG -->
**BACKAN** is an open-source project and its development is open to anyone who wants to participate.
[](https://github.com/pigeonposse/backan/issues)
[](https://github.com/pigeonposse/backan/pulls)
[](https://backan.pigeonposse.com/)
Help us to develop more interesting things.
[](https://pigeonposse.com/?popup=donate)
This software is licensed with **[GPL-3.0](/LICENSE)**.
[](/LICENSE)
_PigeonPosse_ is a āØ **code development collective** āØ focused on creating practical and interesting tools that help developers and users enjoy a more agile and comfortable experience. Our projects cover various programming sectors and we do not have a thematic limitation in terms of projects.
[](https://github.com/pigeonposse)
| | Name | Role | GitHub |
| ---------------------------------------------------------------------------------- | ----------- | ------------ | ---------------------------------------------- |
| <img src="https://github.com/angelespejo.png?size=72" alt="Angelo" style="border-radius:100%"/> | Angelo | Author & Development | [@Angelo](https://github.com/angelespejo) |
| <img src="https://github.com/PigeonPosse.png?size=72" alt="PigeonPosse" style="border-radius:100%"/> | PigeonPosse | Collective | [@PigeonPosse](https://github.com/PigeonPosse) |
<br>
<p align="center">
[](https://pigeonposse.com)
[](https://pigeonposse.com?popup=about)
[](https://pigeonposse.com/?popup=donate)
[](https://github.com/pigeonposse)
[](https://twitter.com/pigeonposse_)
[](https://www.instagram.com/pigeon.posse/)
[](https://medium.com/@pigeonposse)
</p>
<!-- PIGEONPOSSE END ORG -->
<!-- PIGEONPOSSE START MARK -->
<!--
āāāāāāā āāā āāāāāāā āāāāāāāā āāāāāāā āāāā āāā
āāāāāāāāāāāāāāāāāāā āāāāāāāāāāāāāāāāāāāāāā āāā
āāāāāāāāāāāāāā āāāāāāāāāā āāā āāāāāāāāā āāā
āāāāāāā āāāāāā āāāāāāāāā āāā āāāāāāāāāāāāā
āāā āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā āāāāāā
āāā āāā āāāāāāā āāāāāāāā āāāāāāā āāā āāāāā
āāāāāāā āāāāāāā āāāāāāāāāāāāāāāāāāāāāāāā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
āāāāāāāāāāā āāāāāāāāāāāāāāāāāāāāāāāāā
āāāāāāā āāā āāāāāāāāāāāāāāāāāāāāāāāāā
āāā āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
āāā āāāāāāā āāāāāāāāāāāāāāāāāāāāāāāā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
āāāāāāā āāāāāā āāāāāāāāāā āāā āāāāāā āāāā āāā
āāāāāāāāāāāāāāāāāāāāāāāāāāā āāāāāāāāāāāāāāāāā āāā
āāāāāāāāāāāāāāāāāāā āāāāāāā āāāāāāāāāāāāāā āāā
āāāāāāāāāāāāāāāāāāā āāāāāāā āāāāāāāāāāāāāāāāāā
āāāāāāāāāāā āāāāāāāāāāāāāā āāāāāā āāāāāā āāāāāā
āāāāāāā āāā āāā āāāāāāāāāā āāāāāā āāāāāā āāāāā
REPOSITORY: https://github.com/pigeonposse/backan
AUTHORS:
- Angelo (https://github.com/angelespejo)
DEVELOPED BY Angelo š¦š
-->
<!-- PIGEONPOSSE END MARK -->