Generate-examples-index-webpack-plugin NPM

generate-examples-index-webpack-plugin

Webpack plugin to generate an index html page from the examples folder

Installation

npm:

npm install -D generate-examples-index-webpack-plugin

yarn:

yarn add --dev generate-examples-index-webpack-plugin

Usage

Use it as your regular webpack plugin.

// webpack.config.js
const ExamplesGenerator = require('generate-examples-index-webpack-plugin');

module.exports = {
  plugins: [
    new ExamplesGenerator(),
  ],
};

Example of files for the examples folder:

examples/
- foo/
  - example1.ts
  - example1.html
  - example2.html
  - FooComponent.ts
- bar/
  - index1.ts
  - index1.html
- utils/
  - sharedFunctions.ts
  - Class1.ts
  - Class2.ts

Then, this plugin will generate a site with the following index:

foo/
- example1
- example2
bar/
- index1

foo/example1, foo/example2 and bar/index1 are shown because there are html files which creates an entry point.

foo/example1.html will include example1.ts, and bar/index1.html will do the same with bar/index1.ts. foo/example2 will not include nothing automatically but it can still include built files from your application like this <script src="<% htmlWebpackPlugin.options.app %>/entryFile.js"></script>

On the other hand, foo/FooComponentjs and the files inside utils are not shown in the index because they have no associated .html file. As you can imagine, they are just files imported by the other main ones.

Like the previously mentioned app, some values are provided to be used in the html templates used for the templates. You can access them placing <% htmlWebpackPlugin.options.PLACEHOLDER %> in the html code, being PLACEHOLDER one of the following values:

Available placeholders

Index page

Placeholder name	Description
assets	Route to a folder with a copy of the application build results
buildDate	Date of the building time. The resulting string can be customised with the provided date options
examplesFolder	Name of the original examples folder
examplesIndex	HTML code with the generated examples index. Can be customised providing with the `examplesIndexHtmlGenerator` option
projectName	Name of the project, directly from `project.json`
projectVersion	Version of the project, directly from `project.json`
reportLink	Link to the resulting report link generated if the `analyzer` option is not disabled

Examples pages

Placeholder name	Description
app	Relative path to the folder containing the results of the project build
assets	Relative path to the folder with the static assets (internal from the plugin and the content from the `static` option)
backLink	Relative path to the index page
breadcrumbs	HTML code with the breadcrumbs for the current example
buildDate	Date of the building time. The resulting string can be customised with the provided date options
examplesFolder	Name of the original examples folder
projectCss	Relative path to the CSS file generated for the project
projectName	Name of the project, directly from `project.json`
projectVersion	Version of the project, directly from `project.json`

Options

new ExamplesGenerator();

Name	Type	Default	Description
addJsExtension	boolean		Set to `true` if your webpack options `output.filename` has no extension (because it comes from the vendor/file name). If not specified, it will try to guess the correct value from your `webpack.options.output.filename` value
analyzer	boolean	`'assets/analyzer.html`	Path for the file with the analysis results of your examples provided by `webpack-bundle-analyzer`. Leave undefined to disable it
app	string	`'assets/app'`	Where the files of your application will be placed. It's accessible via the `app` placeholder.
assets	string	`'assets'`	Where the assets will be placed.
breadcrumbsHtmlGenerator	function	`undefined`	`function(route)` returning the HTML for the breadcrumbs placeholder. Leave `undefined` to use the default one
buildTimeLocale	string	`'ja'`	How the date (accessible via the `buildTime` placeholder) will be outputted. Locale for `Date.toLocaleString`
buildTimeOptions	object		How the date (accessible via the `buildTime` placeholder) will be outputted. Options for `Date.toLocaleString`
examples	string	`'examples'`	Path were your examples are placed. Accessible with the `examplesFolder` placeholder.
examplesFilterHtmlGenerator	function	`undefined`	`function(entry)` returning the HTML for the filtering box. Leave `undefined` to use the default one
examplesIndexHtmlGenerator	function	`undefined`	`function(entry)` returning the HTML for the examplesIndex placeholder. Leave `undefined` to use the default one
excludeAssets	boolean	`false`	Set to `true` to hide the assets produced by this plugin
extensions	string[]	`['js', 'jsx', 'ts', 'tsx']`	Extensions to check when finding the code file associated to an html page
noEntries	boolean	`false`	Set to `true` if your project has no entry files (webpack is just used to generate examples with this plugin), to avoid the message ERROR in Entry module not found: Error: Can't resolve './src'
outputPath	string	`'examplesBuild'`	Your examples will be built and placed here
packageJson	string	`undefined`	Route to the `package.json` of your application, just to retrieve information as the package name, version... If left `undefined` the plugin will try to find it automatically. It also can be an object with the data directly
static	string	`assets`	Content in this folder will be copied into the `assets` path so it's accessible via the `assets` placeholder
templateIndex	string	`undefined`	Path with the `index.html` to use as a template. Leave `undefined` to use the default one
vendorContent	string[]	`[]`	List of files or libraries to include in the generated vendor file
vendorFolder	string	`undefined`	All the files included in the folder specified by this path will be included in the vendor file
vendorName	string	`vendor`	Name for the generated vendor file