CLI

Installation

pnpm add -D @agrume/cli

Configuration

To configure the CLI, you can either use the command options or create a configuration file.

At the root of your project, create a agrume.config.ts file:

import { defineConfig } from '@agrume/cli'

export default defineConfig({
  externalUrl: 'http://localhost:3000/',
  host: 'localhost',
  port: 8173,
  prefix: '/__agrume__/',
  watch: true,
  // As plugin options, if you use `externalUrl`, you can't use `tunnel` (and vice versa)
  // tunnel: {
  //   type: 'Localtunnel',
  // },
})

The advantage of using a configuration file is that you can share the configuration with the plugin. For example, if you use the Vite plugin, you can write:

import { defineConfig } from 'vite'
import agrume from '@agrume/plugin/vite'
import agrumeConfig from './agrume.config'

export default defineConfig({
  plugins: [
    agrume({
      ...agrumeConfig,
      // other options
    }),
    // ...
  ]
})

agrume

You can use the CLI to start the server:

agrume

It will find the routes in your project and start a Fastify server.

Options

Option	Argument	Description	Default
-p, --port	A number	Port to listen on	3000
-h, --host	A string	Host to listen on	localhost
-e, --entry	A list of strings separated by a comma	The entry files to search for routes	"index.js,index.ts,index.jsx,index.tsx,main.js,main.ts,main.jsx,main.tsx,app.js,app.ts,app.jsx,app.tsx,src/index.js,src/index.ts,src/index.jsx,src/index.tsx,src/main.js,src/main.ts,src/main.jsx,src/main.tsx,src/app.js,src/app.ts,src/app.jsx,src/app.tsx"
--watch	Optional The directory to watch for changes	Watch for changes in the target directory	not provided. If the option is present, defaults to the entry file found
--tunnel	Optional The tunnel type (see the tunnel option in the configuration)	Use a tunnel to access the server	not provided. If the option is present, defaults to the localtunnel tunnel
--allow-unsafe		Allow loading routes from node_modules	false
--cors-regexp	A string	The regular expression to match the origin
--ngrok-domain	A string	The domain to use with Ngrok
--pinggy-subdomain	A string	The subdomain to use with Pinggy
--pinggy-token	A string	The token to use with pinggy

agrume build

You can use the CLI to build the routes:

agrume build

It allows you not being dependent on Agrume to run your backend.

By default, agrume build will write in TypeScript a Fastify server in the build directory. If a port is specified either in the configuration or in the command, you will be able to run the server with npx tsx build/index.mts. Otherwise, you will be able to import a registerServer function from the generated file and use it in your own Fastify server.

Options

Option	Argument	Description	Default
library		The library to compile for. Choices: fastify	"fastify"
-e, --entry	A list of strings separated by a comma	The entry files to search for routes	"index.js,index.ts,index.jsx,index.tsx,main.js,main.ts,main.jsx,main.tsx,app.js,app.ts,app.jsx,app.tsx,src/index.js,src/index.ts,src/index.jsx,src/index.tsx,src/main.js,src/main.ts,src/main.jsx,src/main.tsx,src/app.js,src/app.ts,src/app.jsx,src/app.tsx"
-o, --output	A directory were to write	The output directory	"build"
--disable-logger		Disable the logger of the server	false
--single-file		Generate a single file	false
-p, --port	A string for an environment variable, or a number	The port the server will listen on. By default, it uses the port from the config file. Set a string to select an environment variable, or leave empty to avoid generating listen code.	not provided
-w, --watch	Optional The directory to watch for changes	Watch for changes in the target directory	not provided

For example, if you want to build a Fastify server in the dist directory that listens on the port 1234, you can run:

agrume build fastify --output dist --port 1234

Use as a Fastify plugin

You can generate a function that will register the routes in a Fastify server:

agrume build fastify --output agrume-server --port ""

Then, you can use the generated function in your Fastify server:

import fastify from 'fastify'
import { registerServer } from './agrume-server'

const app = fastify()

registerServer(app)

// Do something with the app, like listening on a port