2.0.0 • Public • Published


A dust helper to render React components.


  • Server & client rendering (using requireJS on the client)
  • Allows passing React props as variadic or explicit params
  • Gracefully fails on rendering errors

Module Definition

dust-react provides the following ways of importing:

  • Pre-compiled ES5 code for use in non-babel'd projects (dust-react/lib, which is also the main entry point when doing require('dust-react'))
  • UMD module for use in the browser (dust-react/dist)

The module is the default export. If you're using CommonJS without babel transpiling import/exports, you'll need to explicitly reference the default export.

const dustHelperReact = require('dust-react').default;


dust-react works in both Node.js and AMD environments. Configuring the helper based on the environment allows loading modules in both contexts.

dustHelperReact(options: object)
Option Type Description
requireFn Function Required - The require function based on the environment
globalContext Object Required - The global context object (global in Node.js and window in the browser)
componentDir String Optional - An absolute path for requiring components in Node.js


import dust from 'dustjs-linkedin';
import dustHelperReact from 'dust-react';
import path from 'path';
dust.helpers = dust.helpers || {};
dust.helpers.react = dustHelperReact({
  requireFn: require,
  globalContext: global,
  componentDir: path.resolve(__dirname, '../component')



Param Type Description
component String Required - the path to require the module
props Object optional - Properties to be passed to React.createElement
namedExport String optional - Uses the default export if not specified

The helper requires a reference to a react component as a string. This is what is used with the require function passed in when creating the helper.

<div id="module-mount">
  {@react component="react-module" props=. /}

This equates to a require statement that looks like the following:


(Note about AMD - all modules are loaded asynchronously, and the rjs optimizer is not yet supported)


Props can also be variadic, allowing you to pass in params to the helper that become React props.

<div id="module-mount">
  {@react component="react-book" title='Boop' pages=10 /}

This is equivalent to:

React.createElement(ReactBook, { title: 'boop', pages: 10 });

Named Exports

By default, dust-react will use the default export of the module. You can optionally specify a named export as well.

<div id="module-mount">
  {@react component="react-module" namedExport="example" props=. /}

This is equivalent to:

const component = require('react-module').example;
// or in ES6
import { example } from 'react-module';

Component Paths

Component paths can be either a relative path or a package path.

  • Relative path: ./local-component/example (must start with a dot-slash)
  • Package path: some-npm-module

Relative Paths -- Node.js vs AMD

Under the hood, every path to a component for AMD becomes a package path. Passing in a relative path will result in requiring the module without the ./. This allows you to reference a local file for rendering server-side and reference the same file from your RequireJS baseUrl.


The tests are written in Jest.

npm test



Package Sidebar


npm i dust-react

Weekly Downloads






Last publish


  • masotime