BACKAN

Appearance

Backan Server ​

Build the backan server with zero config.

🔑 Installation ​

bash
npm install @backan/server
bash
pnpm i @backan/server
bash
yarn add @backan/server
bash
bun add @backan/server
bash
deno add npm:@backan/server

NPM Version

📈 usage ​

js
import {
server
} from '@backan/server'
import {
App
} from 'backan'

// create backan app
const 
app
 = new 
App
( {
 
version
     : '1.0.0',
 
title
       : 'BACKAN sample application',
})

// create server for backan

server
({ 
app
 })

⚙️ Configuration ​

The backan server comes ready to use without any configuration, but this does not mean that we can configure certain aspects of the server if we want.

Here is a list of the available options.

ts
/**
 * Options for server function.
 *
 */
type ServerOpts = {
 /**
  * The `backan` app instance.
  *
  */
 app: App<Env>,
 /**
  * The port to start the server on.
  *
  * @default 80
  */
 port?: number
 /**
  * The hostname to bind the server.
  *
  * @default 'localhost'
  */
 hostname?: string
 /**
  * The protocol to use. Defaults to 'http' unless the port is 443.
  * Note: This will be available soon. Currently this does not modify the port, the service is always on http.
  *
  * @default 'http'
  */
 protocol?: 'http' | 'https',
 /**
  * If true, automatically find an available port if the specified port is in use.
  *
  * @default false
  */
 autoPort?: boolean
 /**
  * If true, You can pass the parameters {port,autoPort,hostname,protocol} as flags. Example: ---port=1312 --autoPort.
  *
  * @default false
  */
 allowFlags?: boolean
 /**
  * Optional callback invoked when the server starts successfully.
  */
 onSuccess?: ( info: ServerInfo ) => Promise<void>
 /**
  * Optional callback invoked when an error occurs.
  */
 onError?: ( opts: {
  /**
   * Server error id.
   */
  id: ServerError,
  /**
   * Error catched in process.
   */
  error: unknown,
  /**
   * Data info of server.
   */
  data: ServerInfo
 } ) => Promise<void>
 onExit?: ( opts: {
  /**
   * Data info of server.
   */
  data: ServerInfo
 } ) => Promise<void>
}

/**
 * Data info of server.
 *
 */
type ServerInfo = {
 /**
  * The server hostname.
  *
  */
 hostname: string
 /**
  * The server port.
  *
  */
 port: number
 /**
  * The server protocol.
  *
  */
 protocol: string
 /**
  * The server url: `${protocol}://${hostname}:${port}`.
  *
  */
 url: string
}

💡 Examples ​

Zero config ​

js
/**
 * Start a server with zero config for BACKAN
 *
 * @see https://backan.pigeonposse.com/guide/server
 */

import { server } from '@backan/server'
import app        from './app.js' // your backan app

await server({ app })

Fully customized ​

js
/**
 * Start a fully customized server for BACKAN
 *
 * @see https://backan.pigeonposse.com/guide/server
 */

import { server } from '@backan/server'
import app        from './app.js' // your backan app

await server( {
 app        : app,
 hostname   : 'localhost',
 protocol   : 'http',
 port       : 1312,
 autoPort   : true,
 allowFlags : true,
 onError    : async ( { id, error } ) => {

  if( id === 'UNEXPECTED' ) console.error( '🐦💔 UNEXPECTED Error' )
  else if( id === 'PORTS-NOT-AVAILABLE' ) console.error( '🐦💥🚢 No ports availables' )
  else if( id === 'PORT-NOT-AVAILABLE' ) console.error( '🐦💥🚢 No port available' )
  else if( id === 'HOSTNAME-NOT-VALID' ) console.error( '🐦💥🌐 Hostname not available' )
  console.error( '\n',error )

 },
 onSuccess : async ( info ) => {

  console.info( '🐦✅ Server info', info )

 },
 onExit : async () => {

  console.warn( '\n\n🐦👋 Fly High Pigeon\n' )

 },
} )