generate-examples-index-webpack-plugin

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

Changelog

1.0.3

• Added options.extensions to allow other code files than .ts and .js (such as .tsx and .jsx)

1.0.2

• assets are copied only if they exist to prevent errors from copy-webpack-plugin

1.0.1

• @webpack-contrib/schema-utils moved to dependencies (not devDependencies)

1.0.0

• First version.