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.