Lead Maintainer: Matt Edelman
Compile-on-the-fly and other development tools for use when building express applications.
The middleware compiler builds your dependencies as they are requested, allowing you to run your express application as-is and not have to set up a watch task.
var app =construx = ;app;
src - The directory of your source files
dest - The destination directory for the compiled files
config - Optional. An object of compilers to enable
To enable a plugin, add it to the config object as follows:
Note: above you also would have the
construx-less construx plugin installed in your project
KrakenJS uses confit and meddleware to configure and manage middleware registration. To use
construx as a
krakenjs development tool, add the following to your application's
middleware section in
"construx":"enabled": true"priority": 35"module":"name": "construx""arguments":"path:./public""path:./.build""css":"module": "construx-less""files": "/css/**/*.css""copier":"module": "construx-copier""files": "**/*"
This will engage the
construx middleware only for the development environment. Note that the two configured plugins are as
an example and your actual plugin set will depend upon your application.
Please rely upon the individual plugins' README for configuration and other requirements information.
- construx-copier - copier for static assets
- construx-dust - DustJS template compiler
- construx-less - Less CSS compiler
- construx-sass - Sass CSS compiler
- construx-stylus - Stylus CSS compiler
How plugins work
A plugin usually would wrap a build step for a particular technology. E.g. construx-dustjs wraps the dustjs template compilation build step. This allows on-the-fly dust template changes to be reflected immediately during development of your application. Other examples of plugins would be CSS compilers such as Less, Sass, or Stylus.
"<plugin key>":"module": "<plugin module name>""files": "<filter on request path>""ext": "<file extension>""precompile": <Function>"postcompile": <Function>
<plugin key>just needs to be a unique string within the other registered plugins.
moduleis the npm package name of your plugin.
filesis a glob string which will try and match the
req.path. If there is a match, the plugin middleware will be engaged
ext(optional) is a replacement for the requested file's extension. E.g. if a
GETrequest comes across for
extis set to
less, the construx middleware will attempt to find a file named
<files source path>/foo.less
precompile(optional) is a function that can run prior to the construx middleware execution for this plugin. Its signature is
(context, callback). Please see description of compile
postcompile(optional) is a function that will run post construx middleware execution for this plugin. Its signature is
(context, callback). A possible use case for
postcompilewould be if the plugin creates any temporary files/directories during compilation that should be deleted.
Middleware process a matched request
req.path is matched to a plugin, construx middleware will open the matched file (using
fs.readFile) and call that plugin's compiler:
config argument is:
paths: dirscontext: context<options>
pathsis an array of lookup paths based on the difference between the filesystem root of the current plugin's files and the currently requested file. E.g. if the request is for
pathsarray will be:
['<root css path>/', '<root css path>/foo/', '<root css path>/foo/bar/']. Use this array in your plugin according to need.
contextis passed through all compile steps and its initial form is:
context =srcRoot: <configured src root>destRoot: <configured dest root>filePath: <usually just reqpath>name: <filePath minus file extension>ext: <optionsext if set>;
Note: There are a couple possible overrides to the context object which you might want to take advantage of. See below.
<options>is the JSON object used to register the plugin (see #Plugin-registration above).
The plugin's compiler will do whatever transformation to the raw buffer, and issue a
callback to the construx middleware
with the transformed file (or an error).
srcPath: If you want to compute the source file differently than the construx middleware, you can add
srcPath to the
context object (in a
precompile step usually) and the construx middleware will use your value instead of its own logic
skipRead: If you don't want the construx middleware to open the source file (because for example, your compiler does that instead)
then set the
skipRead flag to be true
Author a plugin
We have created a template for construx plugins: construx-star. The template
includes the basic pattern of a plugin, preferred unit test/coverage modules, preferred
npm run aliases, and license (Apache 2.0).
You can create a blank github repository and import
construx-star as a starting point.
- Please use the naming convention
If you author and publish a
construx plugin, please let us know so we can add it to our existing plugins list.