Getting started

Front-end developers are often afraid of the backend. They don’t know how to start, what to do, and how to do it. Agrume is a tool that makes developing API endpoints as easy as writing a function. Best of all, it’s type-safe!

Let’s see an example:

import { createRoute } from 'agrume'

const getDogImage = createRoute(
  async () => {
    // `database` is a fake database that should not be accessible from the client

    const dog = database.dogs.findFirst({
      select: ['imageBase64'],
      where: { isGoodBoy: true }
    })

    return dog.imageBase64
  }
)

export const Dog = function () {
  const [dogImage, setDogImage] = useState('')

  useEffect(() => {
    getDogImage().then(setDogImage)
  }, [])

  return <img src={dogImage} />
}

Installation

pnpm add agrume @agrume/plugin

Agrume is agnostic. This means that you can use it with the stack of your choice. We provide plugins for the following tools:

• Babel
• ESBuild
• Farm
• Rolldown
• Rollup
• Rspack
• Vite
• Webpack

Provide this range of plugins is possible thanks to Unplugin and the UnJS team.

Vite

To use Agrume with Vite, you need to add the Agrume plugin to your Vite configuration:

import { defineConfig } from 'vite'
import agrume from '@agrume/plugin/vite'

export default defineConfig({
  plugins: [
    agrume()
    // ...
  ],
  // to prevent some errors
  optimizeDeps: {
    exclude: ['agrume']
  },
})

Other tools

With the same logic as Vite, you can add the Agrume plugin to the configuration of your tool, by importing @agrume/plugin/your-tool.

Babel

Agrume uses Babel under the hood. If you use another tool that the ones listed above, you can use the Babel preset.

First, you need to install the Babel preset and the Agrume internals:

pnpm add -D babel-preset-agrume @agrume/internals

Then, you can create a .babelrc.js file:

const { state } = require('@agrume/internals')

state.set((state) => {
  state.options = {
    // Put your options here
  }
  return state
})

module.exports = function (api) {
  return {
    presets: ['babel-preset-agrume'],
  }
}

Motivation

As a student, I frequently have to build projects in teams and in a short amount of time. These projects require a backend, but many of my teammates prefer to work on the frontend because they are not comfortable with the backend. I wanted to create a tool that would make backend development as easy as frontend development, so that it would be easier to organise the work in teams.

I think that Agrume is great to build prototypes and small projects. However, I don’t know if it’s a good idea to use it in production. I would love to hear your feedback on this!