Migrating a Fastify App to Platformatic Service

Fastify is an excellent choice for building production-ready Node.js applications, but it often requires boilerplate setup due to its core principles:

• Modular Design: Fastify encourages plugins to separate concerns and improve testability (see Plugins).
• Minimal Assumptions: Developers have freedom in architecture, plugins, and patterns.
• Custom Solutions: Fastify provides flexibility over pre-defined standards.

Platformatic Service builds on Fastify, streamlining development with best practices baked in, making it easier to start, scale, and maintain production-ready applications.

This guide walks you through migrating a Fastify app to Platformatic Service.

Example Fastify application

Here’s the structure of the example Fastify app we’ll migrate:

The code for the example Fastify and migrated Platformatic Service applications is available on GitHub.

├── app.js
├── package.json
├── plugins
│   └── data-source.js
├── routes
│   ├── movies.js
│   └── quotes.js
├── server.js
└── test
    └── routes.test.js

Dependencies:

"dependencies": {
  "fastify": "^4.17.0",
  "fastify-plugin": "^4.5.0"
}

Key Components

1. Plugins: Add app-wide decorators (e.g., data source):

// plugins/data-source.js
import fastifyPlugin from 'fastify-plugin';

async function dataSource(app) {
  app.decorate('movies', ['Jaws', 'Star Wars', 'The Wizard of Oz']);
  app.decorate('quotes', [
    "You're gonna need a bigger boat.",
    "May the Force be with you.",
    "Toto, I've a feeling we're not in Kansas anymore."
  ]);
}

export default fastifyPlugin(dataSource);

2. Routes: Define API endpoints

// routes/movies.js
export default async function movieRoutes(app) {
  app.get('/', async () => app.movies);
}

3. App Initialization:

// app.js
import fastify from 'fastify';

export async function buildApp(options = {}) {
  const app = fastify(options);

  app.register(import('./plugins/data-source.js'));
  app.register(import('./routes/movies.js'), { prefix: '/movies' });
  app.register(import('./routes/quotes.js'), { prefix: '/quotes' });

  return app;
}

4. Server Start:

// server.js
import { buildApp } from './app.js';

const app = await buildApp({ logger: { level: 'info' } });
await app.listen({ port: 3042, host: '127.0.0.1' });

Migrating to Platformatic Service

Setup a Platformatic Watt Application

Run the command below and create a Watt application:

mkdir my-app
cd my-app
npx wattpm@latest init

Which will output:

Need to install the following packages:
[email protected]
Ok to proceed? (y) y

[15:48:14.722] DONE (40803): Created a wattpm application in /Users/tmp/my-app.

Then, run npm install to install all the dependencies.

Add a Platformatic Service

To start the Platformatic creator wizard, run the appropriate command for your package manager in your terminal:

npm

npm create platformatic@latest

yarn

yarn create platformatic

pnpm

pnpm create platformatic@latest

This interactive command-line tool will guide you through setting up a new Platformatic project. For this guide, please choose the following options:

- Where would you like to create your project?  => .
- Which kind of project do you want to create?  => @platformatic/service
- What is the name of the service?              => (generated-randomly), e.g. legal-soup
- What is the connection string?                => sqlite://./db.sqlite
- Do you want to create default migrations?     => Yes
- Do you want to create another service?        => No
- Do you want to use TypeScript?                => No
- What port do you want to use?                 => 3042
- Do you want to init the git repository?       => No

After completing the wizard, your Platformatic application will be ready in the specified folder. This includes example migration files, plugin scripts, routes, and tests within your service directory.

note

If the wizard does not handle dependency installation, ensure to run npm/yarn/pnpm install command manually:

Refactor Plugins

Copy over your Fastify plugins without changes:

Original Plugin

import fastifyPlugin from 'fastify-plugin'

/** @param {import('fastify').FastifyInstance} app */
async function dataSource (app) {
  app.decorate('movies', [
    'Jaws',
    'Star Wars',
    'The Wizard of Oz'
  ])

  app.decorate('quotes', [
    'You\'re gonna need a bigger boat.',
    'May the Force be with you.',
    'Toto, I\'ve got a feeling we\'re not in Kansas anymore.'
  ])
}

export default fastifyPlugin(dataSource)

Create a new file, data-source in the plugins folder of your web/service directory and add a new plugin:

/// <reference path="../global.d.ts" />
'use strict'
/** @param {import('fastify').FastifyInstance} fastify  */
module.exports = async function movies(fastify, opts) {
  fastify.decorate('movies', [
    'Jaws',
    'Star Wars',
    'The Wizard of Oz'
  ]);
  
  fastify.decorate('quotes', [
    'You\'re gonna need a bigger boat.',
    'May the Force be with you.',
    'Toto, I\'ve got a feeling we\'re not in Kansas anymore.'
  ]);
};

Refactor Routes

Copy over your routes directory and create new files quotes.js and movies.js. Create a quotes.js route:

/// <reference path="../global.d.ts" />
'use strict'
/** @param {import('fastify').FastifyInstance} fastify */
module.exports = async function (fastify, opts) {
  fastify.get('/quotes', async (request, reply) => {
    return fastify.quotes
  })
}

Create a movies.js route in the routes directory of your service application.

/// <reference path="../global.d.ts" />
'use strict'
/** @param {import('fastify').FastifyInstance} fastify */
module.exports = async function (fastify, opts) {
  fastify.get('/movies', async (request, reply) => {
    return fastify.movies
  })
}

Update Tests

Platformatic provides a programmatic API for testing applications. In your test folder of your service directory, create a new file routes.test.js:

import { test } from 'node:test'
import assert from 'node:assert/strict'

import { buildServer } from '@platformatic/service'

import serviceConfig from '../platformatic.json' assert { type: 'json' }

serviceConfig.server.logger = false

test('Basic API', async (t) => {
  const app = await buildServer(serviceConfig)

  t.after(async () => {
    await app.close()
  })

  await t.test('GET request to /movies route', async () => {
    const response = await app.inject({
      method: 'GET',
      url: '/movies'
    })

    assert.equal(response.statusCode, 200)
    assert.deepEqual(response.json(), [
      'Jaws',
      'Star Wars',
      'The Wizard of Oz'
    ])
  })

  await t.test('GET request to /quotes route', async () => {
    const response = await app.inject({
      method: 'GET',
      url: '/quotes'
    })

    assert.equal(response.statusCode, 200)
    assert.deepEqual(response.json(), [
      'You\'re gonna need a bigger boat.',
      'May the Force be with you.',
      'Toto, I\'ve got a feeling we\'re not in Kansas anymore.'
    ])
  })
})

Why Use Platformatic Service?

Beyond Fastify’s functionality, Platformatic Service offers:

• Metrics with fastify-metrics
• Healthcheck endpoint with @fastify/under-pressure
• OpenAPI specification and Scalar with @fastify/swagger and @scalar/fastify-api-reference
• GraphQL API support with mercurius
• CORS support with @fastify/cors
• Configuration with environment variable validation

Next Steps

• Documentation: Explore Platformatic Service in-depth.
• Discord: Get help from the Platformatic community.
• Platformatic Youtube series: can help get you up and running building apps with Platformatic open-source tools.
• PLatformatic Watt documentation.

See the Platformatic Service Configuration documentation for all the features which can be configured.