{"id":18513161,"url":"https://github.com/yeojz/metalsmith-react-templates","last_synced_at":"2025-04-09T06:32:47.041Z","repository":{"id":27190233,"uuid":"30660488","full_name":"yeojz/metalsmith-react-templates","owner":"yeojz","description":"A metalsmith plugin to render files using React / Preact / JSX based templates.","archived":false,"fork":false,"pushed_at":"2018-09-20T13:32:54.000Z","size":288,"stargazers_count":92,"open_issues_count":1,"forks_count":17,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-24T00:10:06.788Z","etag":null,"topics":["metalsmith","react","static-site-generator","template-engine","templating"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"poteto/elixirconf-2017","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yeojz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-02-11T17:34:42.000Z","updated_at":"2023-08-06T06:20:31.000Z","dependencies_parsed_at":"2022-08-17T17:11:04.628Z","dependency_job_id":null,"html_url":"https://github.com/yeojz/metalsmith-react-templates","commit_stats":null,"previous_names":[],"tags_count":35,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yeojz%2Fmetalsmith-react-templates","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yeojz%2Fmetalsmith-react-templates/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yeojz%2Fmetalsmith-react-templates/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yeojz%2Fmetalsmith-react-templates/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yeojz","download_url":"https://codeload.github.com/yeojz/metalsmith-react-templates/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247992870,"owners_count":21029989,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["metalsmith","react","static-site-generator","template-engine","templating"],"created_at":"2024-11-06T15:36:42.200Z","updated_at":"2025-04-09T06:32:43.538Z","avatar_url":"https://github.com/yeojz.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# metalsmith-react-templates [![npm package][npm-badge]][npm-link]\n\n\u003e A metalsmith templating plugin using JSX templates. Supports React / Preact / React-Router etc.\n\n[![Build Status][build-badge]][build-link]\n[![Coverage Status][coveralls-badge]][coveralls-link]\n[![npm downloads][npm-downloads-badge]][npm-downloads-link]\n[![PRs Welcome][pr-welcome-badge]][pr-welcome-link]\n\n## About\n\n`metalsmith-react-templates` is a [metalsmith](http://www.metalsmith.io/) plugin to render files using JSX templates like [React](https://facebook.github.io/react/) and [Preact](https://github.com/developit/preact).\n\nIt is extensible, and thus could be expanded to support other similar libraries like [Inferno](https://github.com/infernojs/inferno) as long as they have support server-side rendering.\n\n## Installation\n\nUsing [npm](https://www.npmjs.com/):\n\n```\n$ npm install --save metalsmith-react-templates\n```\n\nInstall other dependencies.\nFor example, if you're using just React:\n\n```\n$ npm install react react-dom\n```\n\nIf you're using an older version of React, you may need to install an older version of this package.\n\n| React Version | Package Version |\n|:------------- |:-------------   |\n| 15.x.x        | \u003e 5.x.x         |\n| 0.14.x        | 3.x.x or 4.x.x  |\n| 0.13.x        | 2.x.x           |\n| 0.12.x        | 1.x.x           |\n\nIf you're upgrading, you may want to check out the [Upgrade Notes](/docs/UPGRADE_NOTES.md). For example, react-router v4 is only supported for package versions \u003e 7.0.0\n\nFor more information on engine usage, you can check out the corresponding integration test files. i.e. `integration-[LIBRARY].spec.js`.\n\n## CLI Usage\n\nInstall the node modules and then add the `metalsmith-react-templates` key to your `metalsmith.json` plugins.\n\n```json\n{\n  \"plugins\": {\n    \"metalsmith-react-templates\": true\n  }\n}\n```\n\nIf you want to specify additional options, pass an object:\n\n```json\n{\n  \"plugins\": {\n    \"metalsmith-react-templates\": {\n      \"baseFile\": \"base.html\",\n      \"isStatic\": true,\n      \"directory\": \"templates\"\n    }\n  }\n}\n```\n\n## JavaScript Usage\n\nSimplest use case:\n\n```js\nimport templates from 'metalsmith-react-templates';\n\nmetalsmith.use(templates());\n```\n\nTo specify additional options:\n\n```js\nmetalsmith.use(templates({\n  baseFile: 'base.html'\n  isStatic: true,\n  directory: 'templates'\n}));\n```\n\n## Usage Notes\n\n### Specifying Templates\n\nIf an `rtemplate` field is set in the `yaml` front matter of your markdown files, `metalsmith-react-templates` will use the specified template instead of `Default.jsx`.\n\nYou can also set `templateKey` to other values like `template` and the plugin will use that value (in this case the `template` field) instead of `rtemplate` field in the `yaml` front matter.\n\n### Webpack / Build Systems\n\nIf you import css or any other non-standard JavaScript code using `require`,\nyou might want to make use of the `requireIgnoreExt` to ignore those files.\n\nYou may also add other extensions that are treated as JSX. using `requireTemplateExt`.\n\n### material-ui\n\nIf you are using [`material-ui`](https://github.com/callemall/material-ui/) v1.0, components are not properly styled due to the way `material-ui`'s server-side theming system works.\n\nThe solution is to use a higher-order component (HOC) so that the inline css is rendered when `metalsmith` runs. See [this issue and solution](https://github.com/callemall/material-ui/issues/6822).\n\n### Using the post render hydrator\n\nUsing a custom hydrator via the `postRenderHydrator` option allows you to control how the data generated via the `strategy` is applied on a file. By default, the integrated hydrator only puts the generated React markup in the `contents` attribute of the file. But there are cases where your React code might generate more than just content markup, for example when using [React Helmet](https://github.com/nfl/react-helmet).\n\nBy using a custom strategy and a custom hydrator, you can add additional properties on the processed files and then do whatever you want with it, like render them in your base template or use them in other metalsmith plugins.\n\n[Here is an example](https://gist.github.com/Leimi/b62975a28b202fb6919fa7feb7688f5b) of a custom strategy and hydrator used to make React Helmet work.\n\n## Options\n\nAll parameters are optional.\n\n| Parameter | Default Value | Description\n:-------------|:-------------|:-------------\n| `baseFile` | `null` | Specifies a file which the contents of the react template will render into. \u003cbr /\u003e\u003cbr /\u003e This is similar to the `index.html` file which you `React.render()` your components in. \u003cbr /\u003e\u003cbr /\u003e In your base file, put `{{contents}}` in the location where you want your data will render into. \u003cbr /\u003e\u003cbr /\u003e You may also override this value by placing a baseFile key in your source file's front matter.\n| `baseFileDirectory` | `null` | Sets the directory which your baseFile resides. By default, it assumes your base file is in the same directory as your templates.\n| `defaultTemplate` | `Default.jsx` | The default template file to use if no template is specified. \u003cbr /\u003e\u003cbr /\u003e Set to `''` or `null` if you do not want metalsmith to not apply template transformation on files that do not have a 'template / rtemplate' key present.\n| `directory` | `templates` | Sets the directory which your react templates resides.\n| `extension` | `.html` | Option to rename your files to a specified extension. Set to `null` if you do not want to change the file extension\n| `isStatic` | `true` | Since this is a static site generator, by default, it will render the React Templates using `renderToStaticMarkup()`. \u003cbr /\u003e\u003cbr /\u003e However, you may choose to make a static site generator with React functionalities (similar to first render from server) and subsequently pull page routes via JavaScript / React.\u003cbr /\u003e\u003cbr /\u003e Setting this parameter to `false` will cause templates to be parsed using `renderToString()`.\n| `pattern` | `**/*` | Specifies a file filter pattern.\n| `preserve` | `false` | Stores a copy of un-templated contents into `rawContents` meta which you can access in your React components.\n| `props` | `null` | Accepts a `function` returning props or a `string` containing the props to provide to the template. If `null` the defualt set of props will be returned.\n| `requireIgnoreExt` | `[ ]` | A list of extensions to ignore. \u003cbr /\u003e\u003cbr /\u003e For example, `{requireIgnoreExt: ['.css']}` would ignore declarations like `require('file.css')`\n| `requireTemplateExt` | `['.jsx']` | A list of extensions to treat as JSX.\n| `strategy` | `reactTemplates` (function) | The function handler of different library types\n| `postRenderHydrator` | `null` | Accepts a `function` that takes care of putting the data returned by the strategy in each file object. Takes the current file `data` and the content returned by the strategy in parameters, must return a newly formed `data` object. By default, sets the React generated markup on the `contents` attribute.\n| `templateKey` | `null` | Allows you to specify the key in the markdown file that will serve as the template file name. By default, it is `rtemplate`.\n| `templateTag` | `null` | Accepts a function `pattern(key)` which returns a regex object used to find and replace template tags in your output file. \u003cbr /\u003e\u003cbr /\u003e By default, template tags are assumed to be `{{tag}}`. You may use this to allow for other tag formats (eg. you may want `\u003c!--tag--\u003e` instead). \u003cbr /\u003e \u003cbr /\u003e Check the test case for an example.\n| `tooling` | `{ }` | Options to pass into the `babel` transpiler.\n\n\n#### Deprecated Options\n\n| Parameter | Default Value | Description\n:-------------|:-------------|:-------------\n| `propsKey` | `null` | Specifies a key containing the props to provide to the template. If left unspecified, a generic props containing all keys is provided.\n| `noConflict` | `true` | By default, this plugin will read from the `rtemplate` key in your `yaml` front matter. However, if this is the only templating plugin, you may set `noConflict` to `false` to use the `template` key instead.\n\n## Related\n\n-   [jsx-render-engine](https://www.npmjs.com/package/jsx-render-engine) - The core of this module, also published as a independent package.\n\n## License\n\nMIT [`License`](/LICENSE) © Gerald Yeo\n\n[npm-badge]: https://img.shields.io/npm/v/metalsmith-react-templates.svg?style=flat-square\n[npm-link]: https://www.npmjs.com/package/metalsmith-react-templates\n\n[build-badge]: https://img.shields.io/circleci/project/github/yeojz/metalsmith-react-templates/master.svg?style=flat-square\n[build-link]: https://circleci.com/gh/yeojz/metalsmith-react-templates\n\n[coveralls-badge]: https://img.shields.io/coveralls/yeojz/metalsmith-react-templates/master.svg?style=flat-square\n[coveralls-link]: https://coveralls.io/github/yeojz/metalsmith-react-templates\n\n[npm-downloads-badge]: https://img.shields.io/npm/dt/metalsmith-react-templates.svg?style=flat-square\n[npm-downloads-link]: https://www.npmjs.com/package/metalsmith-react-templates\n\n[pr-welcome-badge]: https://img.shields.io/badge/PRs-Welcome-ff69b4.svg?style=flat-square\n[pr-welcome-link]: https://github.com/yeojz/metalsmith-react-templates/blob/master/CONTRIBUTING.md\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyeojz%2Fmetalsmith-react-templates","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyeojz%2Fmetalsmith-react-templates","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyeojz%2Fmetalsmith-react-templates/lists"}