Configuration

Agrume is designed to be as simple as possible. It doesn’t need any configuration to work. However, you can configure it to suit your needs.

prefix

By default, Agrume will prefix all your routes with /api. You can change this prefix by passing the prefix option to the plugin:

// ...

export default defineConfig({
  plugins: [
    agrume({
      prefix: '/my-api'
    })
    // ...
  ]
})

baseUrl

By default, Agrume will make requests to the same host as the frontend. However, you can change this by passing the baseUrl option to the plugin:

// ...

export default defineConfig({
  plugins: [
    agrume({
      baseUrl: 'http://localhost:3000/'
    })
    // ...
  ]
})

Note

It can be useful if you host your frontend and backend on different servers or different processes.

Note

The difference between prefix and baseUrl is that prefix will impact both the transformation step (the frontend) and the registration step (the backend), while baseUrl will only impact the transformation step (the frontend).

useMiddleware

By default, Agrume will use the Vite server to serve your API. However, you can use your own server by passing the useMiddleware option to the plugin:

// ...
import { server } from './server'

export default defineConfig({
  plugins: [
    agrume({
      useMiddleware: server.use.bind(server),
    })
    // ...
  ]
})

The useMiddleware option takes a function that takes a Connect-like middleware as an argument. Here is an example of a Connect-like server:

import { createServer } from "node:http"
import connect from "connect"

const app = connect()
const server = createServer(app)

server.listen(3000)

export { app as server }

Many backend frameworks can use Connect-like middleware. For example, Express can use Connect-like middleware. You can use it as a server:

import express from 'express'

const app = express()
const server = app.listen(3000)

export { app as server }

But please, don’t use Express. See “Why you should drop ExpressJS” by Romain Lanz.

logger

By default, Agrume does not log anything. However, you can pass a logger to the plugin to log the requests:

// ...

export default defineConfig({
  plugins: [
    agrume({
      logger: {
        info: console.info,
        error: console.error,
      }
    })
    // ...
  ]
})

You can use fs.writeFileSync instead of console.log to log the requests to a file.

// ...

export default defineConfig({
  plugins: [
    agrume({
      logger: {
        info: (...args) => fs.writeFileSync('info.log', args.join(' ') + '\n', { flag: 'a' }),
        error: (...args) => fs.writeFileSync('error.log', args.join(' ') + '\n', { flag: 'a' }),
      }
    })
    // ...
  ]
})

tunnel

By default, Agrume will not use a tunnel. However, sometimes you need to use a tunnel to access your backend due to network restrictions. You can use a tunnel by passing the tunnel option to the plugin:

// ...

export default defineConfig({
  plugins: [
    agrume({
      tunnel: { type: 'bore' }
    })
    // ...
  ]
})

Agrume supports the following tunnel types:

Important

For some tunnel types, you may need to install the tunnel CLI. For example, to use the bore tunnel, you need to install the bore CLI.

Note

The tunnel URL is deterministic. This means that if you restart the tunnel, the URL will be the same.

Note

You may want to use the Agrume CLI to start the tunnel easily. See the CLI section.