fastify-better-flash

This plugin is inspired by the @fastify/flash plugin. The main difference is the way it access the messages, using a "dot syntax" and it has a better typescript support. See below for more details.

Supports Fastify versions 4.x

Install

1npm i fastify-better-flash @fastify/secure-session

1pnpm i fastify-better-flash @fastify/secure-session

1yarn add fastify-better-flash @fastify/secure-session

Usage

Flash messages are stored in the session. First, we need to register the session plugin: @fastify/secure-session.

1const fastify = require('fastify')()
2const fastifySession = require('@fastify/secure-session')
3
4fastify.register(fastifySession, {
5  // adapt this to point to the directory where secret-key is located
6  key: fs.readFileSync(path.join(__dirname, 'secret-key')),
7  cookie: {
8    // options from setCookie, see https://github.com/fastify/fastify-cookie
9  }
10})
11fastify.register(require('fastify-better-flash'))
12
13fastify.listen({ port: 3000 })

Usage

In your route handler you can use the flash method to set a flash message. Let's say that we want to have the following messages:

  success: boolean
  validations: {
    errors: Array<{ field: string, message: string }>
  }
  genericError: string

we can set them in the route handler like this:

1
2fastify.get('/', async (request, reply) => {
3  request.flash('success', true)
4  request.flash('validations.errors', [{ field: 'email', message: 'Email is required' }])
5  request.flash('genericError', 'Something went wrong')
6})
7

Then we can consume them like this:

1
2fastify.get('/flash', async (request, reply) => {
3  const success = reply.flash('success')
4  // Note that we can access the nested object using the dot notation
5  const validation = reply.flash('validations')
6  const validationErrors = validation ? validation.errors : []
7  // it works with arrays too, this will return the first error field property
8  const validationErrors = reply.flash('validations.errors.0.field')
9  const genericError = reply.flash('genericError')
10  return { success, validationErrors, genericError }
11})
12

Typescript

You can define the schema of your flash messages using typescript. By using the fastify-better-flash module you can customize the interface FlashSessionType that be extended to define the schema of your flash messages.

1
2declare module 'fastify-better-flash' {
3  export interface FlashSessionType {
4    // Define your flash message schema here
5    success: boolean
6    validations: {
7      errors: Array<{ field: string, message: string }>
8    }
9  }
10}
11

And then in your route handler you can use the flash method to set a flash message.

1
2fastify.get('/', async (request, reply) => {
3  // Also the keys will be typed
4  request.flash('success', 'This is a success message') // This will not compile
5
6  const validationErrors = reply.flash('validations.errors') // This will have the correct types
7  return reply.redirect('/flash')
8})
9

By design the getter method flash will alaways return the type that you have defined or undefined. This is meant to signal the developer that the presence of the object in the flash session storage is not guaranteed on every request.

Acknowledgements

License

Licensed under MIT.