esmrouter
v1.1.0
Published
Make npm web modules available through automated express router.
Downloads
7
Readme
ESMrouter
Express router to export ESM npm packages.
Brief
ESMrouter creates an Express router that makes all browser-enabled npm
packages
installed trough npm install
automatically available client side by its
package name.
Example:
- In your project:
npm install my_package
- In your client app:
import my_package from my_package
Index
Features
Automatically serve all browser-enabled NPM packages making them available client side.
Provide an importmap local that can be used to provide a fully automated importmap in your layout view's head so that you can import npm packages just by its package name client side.
Then just npm install modules in your project and import them by its name client side.
Highly customisable. Even though defaults will be just fine in almost all cases.
Installation
npm install esmrouter
Usage
Load esmrouter:
const esmrouter = require('esmrouter');
Create an express router to serve all installed packages:
const modulesRouter = esmrouter(express, options);
Where:
express: The express utility framework you already have installed.
options: An (optional) options object (see the Options section).
Mount it to your express app:
app.use(modulesRouter);
Quick Start
Following are more step by step instructions to get it working from scratch with simple express project:
Creating a new Expres project:
- Create an express project with xprgen and
--esmr
modifier:
npx xprgen --esmr myApp
cd myApp
npm install
- You're done!!
…just npm install your browser-enabled packages and import them by its package name client side.
To see them working just start your new server in dev mode (so you don't need to restart it at every change):
DEBUG=myapp:* npm run dev
Example:
Install the smarkform npm package:
npm install smarkform
Edit any view (i.e. 'views/index.pug') and append the following code:
script(type="module").
import smarkform from "smarkform";
console.log(smarkform);
Now, if you connect to http://localhost:3000 and open the
develpoer console (usually by hitting <F12>
key), you'll confirm that the module was successfully loaded.
Adding ESMrouter to existing express projects
- Go to your existing Express project directory (say *./myApp):
cd myApp
- Install esmrouter
npm install esmrouter
- Create a file at 'routes/node_modules.js' with following contents:
const express = require('express');
const esmrouter = require('esmrouter');
const modules_options = {
warn: false,
}
const router = esmrouter(express, modules_options);
module.exports = router;
- Edit the 'app.js' file and add the following lines just after the
var app = express();
line:
const modulesRouter = require('./routes/node_modules');
app.use(modulesRouter);
- Edit the default layout template (say 'views/layout.pug' in case you use Pug as your template engine) and add the following line in the head section:
script(type='importmap')!=importmap
This maka all templates using this layout to load the importmap file generated by ESMrouter that will allow you to import browser-enabled npm packages just by their package name instead of their actual route (/node_modules/<package_name> by default).
That's All!!
Now you can npm install your preferred ESM packages from npm and import them in all your project views by its package name (as long as they use that layout file) without any extra bundling/compilation step...
Options
target
Control which modules are checked.
- Valid options:
prod
: Scan production dependencies only.dev
: Like "prod", but also include devDependencies.all
Scan all modules under node_modules, including sub-dependencies.
- Default value: "prod".
include
Allow to include packages without browser field defined using main field as entry point.
- Valid options:
- A string containing an exact package name to be included.
- A RegExp that package name must satisfy to be included.
- An array with many of the former.
- Default value:
[]
- Examples:
/\bwc-/
Include all scoped and non-scoped packages whose name begins with "wc-" (standing for "Web Component").
path
Specify the base for the route path of all served modules.
- Default value: "node_modules".
- Can be empty ("") to mount all at the root of the router.
extension
Specify the file extension for the route path of all served modules.
- Default value: "mjs"
content_type
Specify the value of the content-type header.
- Default value: "application/javascript"
warn
Specify wether to warn or not when a package with a non string "browser" property in its package.json is found.
- Default value: true.
- Note: Warning message also provide a hint to disable it.
local_importmap
Defines the name of the local property where the importmap string is provided (falsy value disables it).
- Default value: "importmap".
local_imports
Defines the name of the local property where the imports object is provided (falsy value disables it).
- Default value: false (disabled).
License
Acknowledgements
We would like to express our gratitude to the open source community for their valuable contributions and feedback.