feat: support generation of ES modules based templates (#541)

* feat: support generation of esm modules template

* Add unit tests for es modules template generation

* Update `README.md` with `--esm` flag option

* Drop commented-out inject callback blocks in `templates/app-esm/test/*`

* fixup! Add unit tests for es modules template generation

* Add `package.json` with `type: 'module'` in `app-esm` 

* Configure `@istanbuljs/esm-loader-hook` for ESM template code coverage

README.md

@@ -280,6 +280,7 @@ it will be overwritten. Use the `--integrate` flag with care.
 
 | Description | Full command |
 | --- | --- |
+| To generate ESM based JavaScript template | `--esm` |
 | Use the TypeScript template | `--lang=ts`, `--lang=typescript` |
 | Overwrite it when the target directory is the current directory (`.`) | `--integrate`|
 | For JavaScript template, optionally includes Standard linter to fix code style issues | `--standardlint`|

generate.js

@@ -114,12 +114,16 @@ function generate (dir, template) {
 
         pkg.main = template.main
 
+        pkg.type = template.type
+
         pkg.scripts = Object.assign(pkg.scripts || {}, template.scripts)
 
         pkg.dependencies = Object.assign(pkg.dependencies || {}, template.dependencies)
 
         pkg.devDependencies = Object.assign(pkg.devDependencies || {}, template.devDependencies)
 
+        pkg.tap = template.tap
+
         log('debug', 'edited package.json, saving')
         writeFile('package.json', JSON.stringify(pkg, null, 2), (err) => {
           if (err) {
@@ -159,6 +163,19 @@ function cli (args) {
   } else {
     template = { ...javascriptTemplate }
 
+    if (opts.esm) {
+      template.dir = 'app-esm'
+      template.type = 'module'
+      template.tap = {
+        'node-arg': [
+          '--no-warnings',
+          '--experimental-loader',
+          '@istanbuljs/esm-loader-hook'
+        ]
+      }
+      template.devDependencies['@istanbuljs/esm-loader-hook'] = cliPkg.devDependencies['@istanbuljs/esm-loader-hook']
+    }
+
     if (opts.standardlint) {
       template.scripts = {
         ...template.scripts,

package.json

@@ -62,6 +62,7 @@
     "@fastify/autoload": "^5.0.0",
     "@fastify/pre-commit": "^2.0.2",
     "@fastify/sensible": "^5.0.0",
+    "@istanbuljs/esm-loader-hook": "0.2.0",
     "@types/node": "^18.0.0",
     "@types/tap": "^15.0.5",
     "concurrently": "^7.0.0",

templates/app-esm/README.md

@@ -0,0 +1,24 @@
+# Getting Started with [Fastify-CLI](https://www.npmjs.com/package/fastify-cli)
+
+This project was bootstrapped with Fastify-CLI.
+
+## Available Scripts
+
+In the project directory, you can run:
+
+### `npm run dev`
+
+To start the app in dev mode.\
+Open [http://localhost:3000](http://localhost:3000) to view it in the browser.
+
+### `npm start`
+
+For production mode
+
+### `npm run test`
+
+Run the test cases.
+
+## Learn More
+
+To learn Fastify, check out the [Fastify documentation](https://www.fastify.io/docs/latest/).

templates/app-esm/__gitignore

@@ -0,0 +1,58 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+
+# Runtime data
+pids
+*.pid
+*.seed
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (http://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules
+jspm_packages
+
+# Optional npm cache directory
+.npm
+
+# Optional REPL history
+.node_repl_history
+
+# 0x
+profile-*
+
+# mac files
+.DS_Store
+
+# vim swap files
+*.swp
+
+# webstorm
+.idea
+
+# vscode
+.vscode
+*code-workspace
+
+# clinic
+profile*
+*clinic*
+*flamegraph*

templates/app-esm/app.js

@@ -0,0 +1,29 @@
+'use strict'
+
+import path from 'path'
+import AutoLoad from '@fastify/autoload'
+import { fileURLToPath } from 'url'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+
+export default async function (fastify, opts) {
+  // Place here your custom code!
+
+  // Do not touch the following lines
+
+  // This loads all plugins defined in plugins
+  // those should be support plugins that are reused
+  // through your application
+  fastify.register(AutoLoad, {
+    dir: path.join(__dirname, 'plugins'),
+    options: Object.assign({}, opts)
+  })
+
+  // This loads all plugins defined in routes
+  // define your routes in one of these
+  fastify.register(AutoLoad, {
+    dir: path.join(__dirname, 'routes'),
+    options: Object.assign({}, opts)
+  })
+}

templates/app-esm/package.json

@@ -0,0 +1,3 @@
+{
+    "type": "module"
+}

templates/app-esm/plugins/README.md

@@ -0,0 +1,16 @@
+# Plugins Folder
+
+Plugins define behavior that is common to all the routes in your
+application. Authentication, caching, templates, and all the other cross
+cutting concerns should be handled by plugins placed in this folder.
+
+Files in this folder are typically defined through the
+[`fastify-plugin`](https://github.com/fastify/fastify-plugin) module,
+making them non-encapsulated. They can define decorators and set hooks
+that will then be used in the rest of your application.
+
+Check out:
+
+* [The hitchhiker's guide to plugins](https://www.fastify.io/docs/latest/Guides/Plugins-Guide/)
+* [Fastify decorators](https://www.fastify.io/docs/latest/Reference/Decorators/).
+* [Fastify lifecycle](https://www.fastify.io/docs/latest/Reference/Lifecycle/).

templates/app-esm/plugins/sensible.js

@@ -0,0 +1,13 @@
+'use strict'
+
+import fp from 'fastify-plugin'
+import sensible from '@fastify/sensible'
+
+/**
+ * This plugins adds some utilities to handle http errors
+ *
+ * @see https://github.com/fastify/fastify-sensible
+ */
+export default fp(async (fastify) => {
+  fastify.register(sensible)
+})

templates/app-esm/plugins/support.js

@@ -0,0 +1,12 @@
+'use strict'
+
+import fp from 'fastify-plugin'
+
+// the use of fastify-plugin is required to be able
+// to export the decorators to the outer scope
+
+export default fp(async function (fastify, opts) {
+  fastify.decorate('someSupport', function () {
+    return 'hugs'
+  })
+})

templates/app-esm/routes/README.md

@@ -0,0 +1,27 @@
+# Routes Folder
+
+Routes define routes within your application. Fastify provides an
+easy path to a microservice architecture, in the future you might want
+to independently deploy some of those.
+
+In this folder you should define all the routes that define the endpoints
+of your web application.
+Each service is a [Fastify
+plugin](https://www.fastify.io/docs/latest/Reference/Plugins/), it is
+encapsulated (it can have its own independent plugins) and it is
+typically stored in a file; be careful to group your routes logically,
+e.g. all `/users` routes in a `users.js` file. We have added
+a `root.js` file for you with a '/' root added.
+
+If a single file become too large, create a folder and add a `index.js` file there:
+this file must be a Fastify plugin, and it will be loaded automatically
+by the application. You can now add as many files as you want inside that folder.
+In this way you can create complex routes within a single monolith,
+and eventually extract them.
+
+If you need to share functionality between routes, place that
+functionality into the `plugins` folder, and share it via
+[decorators](https://www.fastify.io/docs/latest/Reference/Decorators/).
+
+If you're a bit confused about using `async/await` to write routes, you would
+better take a look at [Promise resolution](https://www.fastify.io/docs/latest/Reference/Routes/#promise-resolution) for more details.

templates/app-esm/routes/example/index.js

@@ -0,0 +1,7 @@
+'use strict'
+
+export default async function (fastify, opts) {
+  fastify.get('/', async function (request, reply) {
+    return 'this is an example'
+  })
+}

templates/app-esm/routes/root.js

@@ -0,0 +1,7 @@
+'use strict'
+
+export default async function (fastify, opts) {
+  fastify.get('/', async function (request, reply) {
+    return { root: true }
+  })
+}

templates/app-esm/test/helper.js

@@ -0,0 +1,39 @@
+'use strict'
+
+// This file contains code that we reuse
+// between our tests.
+
+import helper from 'fastify-cli/helper.js'
+import path from 'path'
+import { fileURLToPath } from 'url'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+const AppPath = path.join(__dirname, '..', 'app.js')
+
+// Fill in this config with all the configurations
+// needed for testing the application
+function config () {
+  return {}
+}
+
+// automatically build and tear down our instance
+async function build (t) {
+  // you can set all the options supported by the fastify CLI command
+  const argv = [AppPath]
+
+  // fastify-plugin ensures that all decorators
+  // are exposed for testing purposes, this is
+  // different from the production setup
+  const app = await helper.build(argv, config())
+
+  // tear down our app after we are done
+  t.teardown(app.close.bind(app))
+
+  return app
+}
+
+export {
+  config,
+  build
+}

templates/app-esm/test/plugins/support.test.js

@@ -0,0 +1,26 @@
+'use strict'
+
+import { test } from 'tap'
+import Fastify from 'fastify'
+import Support from '../../plugins/support.js'
+
+test('support works standalone', async (t) => {
+  const fastify = Fastify()
+  fastify.register(Support)
+
+  await fastify.ready()
+  t.equal(fastify.someSupport(), 'hugs')
+})
+
+// You can also use plugin with opts in fastify v2
+//
+// test('support works standalone', (t) => {
+//   t.plan(2)
+//   const fastify = Fastify()
+//   fastify.register(Support)
+//
+//   fastify.ready((err) => {
+//     t.error(err)
+//     t.equal(fastify.someSupport(), 'hugs')
+//   })
+// })

templates/app-esm/test/routes/example.test.js

@@ -0,0 +1,13 @@
+'use strict'
+
+import { test } from 'tap'
+import { build } from '../helper.js'
+
+test('example is loaded', async (t) => {
+  const app = await build(t)
+
+  const res = await app.inject({
+    url: '/example'
+  })
+  t.equal(res.payload, 'this is an example')
+})

templates/app-esm/test/routes/root.test.js

@@ -0,0 +1,13 @@
+'use strict'
+
+import { test } from 'tap'
+import { build } from '../helper.js'
+
+test('default root route', async (t) => {
+  const app = await build(t)
+
+  const res = await app.inject({
+    url: '/'
+  })
+  t.same(JSON.parse(res.payload), { root: true })
+})