turbo-nest

Use Turbo in your NestJS app! 🚀

---

A Nest plugin that wraps your existing server-side templates to make them Turbo-compatible.

Intended to be used in MVC Nest apps. This plugin makes use of Nest's platform-agnosticism techniques, so all templating engines are supported (assuming that they've been properly configured in your app)

Supports both Express- and Fastify-based apps.

Installation

Install the package in your existing Nest app:

npm install --save turbo-nest

Usage

This package exports two primary method decorators...

• @RenderTurboFrame()
• @RenderTurboStream()

...and a few shorthand method decorators:

• @RenderTurboStreamAppend()
• @RenderTurboStreamPrepend()
• @RenderTurboStreamReplace()
• @RenderTurboStreamUpdate()
• @RenderTurboStreamRemove()
• @RenderTurboStreamBefore()
• @RenderTurboStreamAfter()

import { RenderTurboFrame, RenderTurboStream } from 'turbo-nest';

@RenderTurboFrame(view: string, options: RenderTurboFrameOptions)

Given a template file like this...

// profile.ejs

<p><%= firstName %></p>

...and a typical controller like this...

// users.controller.ts

@Controller()
class UsersController {

  /**
   * 🚨 Important note for Fastify apps:
   * depending on how your app configures
   * the view engine, you may need to include
   * the template file extension, e.g.,
   * `@RenderTurboFrame('profile.ejs', { options })
   */
  @RenderTurboFrame('profile', {
    id: 'profile-frame', // Required
  })
  @Get()
  getProfile() {
    return {
      firstName: 'John'
    }
  }
}

...expect an HTTP response like this:

Content-Type: text/html;

<turbo-frame id="profile-frame">
  <p>John</p>
</turbo-frame>

All Turbo Frame HTML attributes are supported, including id, src, target, loading, busy, disabled, autoscroll, and autoscrollBlock.

See the RenderTurboFrameOptions interface for type definitions.

@RenderTurboStream(view: string, options: RenderTurboStreamOptions)

Given a template file like this...

// todo.ejs

<li><%= todo %></li>

...and a typical controller like this...

// users.controller.ts

@Controller()
class UsersController {

  /**
   * 🚨 Important note for Fastify apps:
   * depending on how your app configures
   * the view engine, you may need to include
   * the template file extension, e.g.,
   * `@RenderTurboStream('todo.ejs', { options })
   */
  @RenderTurboStream('todo', {
    action: 'append', // Required
    target: 'todo-frame' // Required
  })
  @Get()
  getTodo() {
    return {
      todo: 'buy milk'
    }
  }
}

...expect an HTTP response like this:

Content-Type: text/vnd.turbo-stream.html;

<turbo-stream action="append" target="todo-frame">
  <template>
    <li>buy milk</li>
  </template>
</turbo-stream>

See the RenderTurboStreamOptions interface for type definitions.

@RenderTurboStreamAppend(view: string, options: Omit<RenderTurboStreamOptions, 'action'>)

This is a convenience decorator that's equivalent to @RenderTurboStream('view', { action: 'append', ...options })

See the Turbo documentation for additional info.

@RenderTurboStreamPrepend(view: string, options: Omit<RenderTurboStreamOptions, 'action'>)

This is a convenience decorator that's equivalent to @RenderTurboStream('view', { action: 'prepend', ...options })

See the Turbo documentation for additional info.

@RenderTurboStreamReplace(view: string, options: Omit<RenderTurboStreamOptions, 'action'>)

This is a convenience decorator that's equivalent to @RenderTurboStream('view', { action: 'replace', ...options })

See the Turbo documentation for additional info.

@RenderTurboStreamUpdate(view: string, options: Omit<RenderTurboStreamOptions, 'action'>)

This is a convenience decorator that's equivalent to @RenderTurboStream('view', { action: 'update', ...options })

See the Turbo documentation for additional info.

@RenderTurboStreamRemove(options: Omit<RenderTurboStreamOptions, 'action'>)

This is a convenience decorator that's equivalent to @RenderTurboStream({ action: 'remove', ...options }).

⚠️ Note that unlike the other @RenderTurboStream decorators, the view argument is omitted here because, per the Turbo documentation, inner HTML is not needed.

@RenderTurboStreamBefore(view: string, options: Omit<RenderTurboStreamOptions, 'action'>)

This is a convenience decorator that's equivalent to @RenderTurboStream('view', { action: 'before', ...options })

See the Turbo documentation for additional info.

@RenderTurboStreamAfter(view: string, options: Omit<RenderTurboStreamOptions, 'action'>)

This is a convenience decorator that's equivalent to @RenderTurboStream('view', { action: 'after', ...options })

See the Turbo documentation for additional info.

Found a bug? 🪲

File an issue!