Skip to main content

Intro to OA Merge

Let's discover OA Merge in less than 5 minutes.

What you'll need

Node.js version 16.14 or above.

Initialize the Project

Create a new directory and initialize npm:

mkdir my-api
cd my-api
npm init -y

Install dependencies:

npm install --save-dev oamerge @oamerge/generator-routes
  • oamerge - The core CLI.
  • @oamerge/generator-routes - OA Merge is a plugin-based system, this one generates output for routers.

Create your API

Add an API endpoint for GET /hello by adding the file api/paths/hello/[email protected] with this:

export const summary = 'Says Hello'
export const description = 'Simple example using the NodeJS http request/response model.'
export default async (request, response) => {
response.statusCode = 200
response.setHeader('Content-Type', 'text/plain')
response.end('Hello World!')

Configure OA Merge

Add a configuration file oamerge.config.js with this:

import routes from '@oamerge/generator-routes'
export default {
input: './api',
output: './build',
generators: [

And to your package.json file, add a run script for building:

"scripts": {
"run": "oamerge -c"

Run the Server

OA Merge does not have opinions about how you handle requests, so in this demo we're using the NodeJS createServer for simplicity.

Add a file server.js and put in it:

import { createServer } from 'node:http'
import { routes } from './build/routes.js'

const server = createServer((request, response) => {
// A very rudimentary router, as OA Merge does not ship one. (On purpose!)
for (const { path, method, handler } of routes) {
if (request.url === path && request.method.toLowerCase() === method) {
return handler(request, response)

server.listen(3000, '', () => {
console.log('Server running!')

Now open up to see the server response.