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.