Skip to content

CodeCoupler Webpack Features

All the files inside of the src folder will be compiled to work with all browsers specified in the .browserslistrc. The files inside of the folder static will just copied and html files will be injected with code pointing to the compilation result of the src folder.

Furthermore before any commit, staged .ts, .vue, .js and .css files inside the src folder will be checked by the associated linter. If any of these checks fail (process exits with non-zero code), the commit will be aborted. So you have first to cleanup your code and your repository never receive ugly code.

If many files have to be fixed you can use the command npm run lint:fix to try to fix all the files at once automatically.

Note: GIT commits will ignore the dist, the node_modules folder and any packages generated by npm pack.

The following chapters explain what exactly will be done with specific file types.

Build Results of JS and TS Files

All *.js and *.ts files within the folder src that will be imported will be bundled in one file into the dist folder. The name specified in the package.json will be used as filename. You can also change the filename in bundle.jsName (see Configuration Reference).

Webpack will start with index.js as entry point. You can write here your init code and import from here further modules.

You can use modern ES6 syntax and use the ES6 modules standard in all of your JavaScript and TypeScript files. Using the integrated Bolierplate you are even prepared for experimental features (stage 3) like public and private field declarations in classes or decorators.

JavaScript and TypeScript files will be linted (ESLint), format checked (Prettier), type checked if needed (typescript), compiled (babel) to run on targeted browsers that are specified in .browserlistrc. based on the configuration .babelrc, mangled and minimized (terser) and finally a Source Map file will be created.

Build Results of CSS Files

All required CSS files will be bundled in one file into the dist folder. The name specified in the package.json will be used as filename. You can also change the filename in bundle.cssName (see Configuration Reference). To require a CSS file just put an import "./path/to/your/file.css"; in any of your JavaScript or TypeScript files.

You can use modern and pure CSS without thinking about vendor prefixes or browser inconsistencies.

Your CSS will be converted and extended with polyfills (postcss-preset-env) and vendor prefixes (autoprefixer) based on your targeted browsers specified in .browserlistrc, optimized and minimized (cssnano) and finally a Source Map file will be created.

Read more about all the modern CSS you can use here: preset-env

Note: Reference to images in the static folder with url() statements like they would be in the same folder. For example to reference to logo.png in the root of the folder static you have to write url(logo.png)

Build Results of CSS Module Files

All required CSS files which ends with *.module.css will be handled exactly like the other CSS files described above. Furthermore you can use the pseudo selectors :local and :global to define the scope of CSS classes.

The default scope is global. If can specify other scopes like local or pure by renaming the file ending to *.module-global.css (default), *.module-local.css or *.module-pure.css.

Read more about the different scopes here: CSS Module Scopes

Read more about CSS modules: CSS Modules

Build Results of VUE Files

You can use .vue files in the src folder which will be compiled into your final .js and .css files. You can use standard JavaScript inside of the script tag or class style TypeScript vue instances Documentation.

Note: The style tag normally must not specified with with the lang attribute to use modern CSS. It will always be parsed like any other CSS file (read above). But to work together in combination with the the buildin Vetur validator you should use lang="postcss".

Note: Vue is included as dependency by default. So if you install cc-webpack you do not need to install vue in your project. Just use import Vue from "vue"; and you can start writing Vue Applications. If you do not want to include the Vue library into your bundle run this command: npm i @cc-external/vue.

Build Results of HTML Files

You can place HTML files inside the src folder and include them content in two ways. You can bundle them into the resulting JavaScript file, or keep them in seperate files and load them dynamically if needed. The second method keeps your bundled JavaScript file smaller, but it needs an additional configuration on the part of the user of your library.

Please note that if you write libraries that will be published as node modules and afterwards included by cc-webpack-externals-plugin you should not load the HTML content dynamically. In this case it is better to bundle the HTML files into your library. Even if this were possible, it requires some work to include your library, which makes the whole thing unnecessarily complicated.

Bundle into the JavaScript File

All HTML files will be included in the final JavaScript bundle if you require them with import htmlText from "./path/to/your/file.html"; in any of your JavaScript or TypeScript files. You can access to the content of the HTML file via the variable defined in this import statement.

1
2
import htmlText from "./path/to/your/file.html";
let resultingHtml = htmlText;

Load them dynamically from separate files

You can use the following syntax to load an HTML file dynamically:

1
2
3
import(/* webpackChunkName: "filename.html" */ "./path/to/your/filename.html").then((htmlText) => {
  console.info(htmlText.default);
});
  • The name after webChunkName in the "webpack magic comment" will be used as basename for the separate file. It is advisable to use the same name as the HTML file.
  • Please note how to get the content of the HTML file by reading the field .default.

All separated files will be saved in a subdirectory of the dist folder. The name of this subfolder is by default parts. You can change this name in bundle.chunkSubfolder the (see Configuration Reference).

If you deploy your library the end user will place the files of course wherever he wants. Therefore your library has to know from where to load the separated files. The user of the library must define the path to your library as follows:

1
2
3
4
5
<script>
  window.pathToYourLibrary = "path/to/your/library/";
</script>
<link href="your-library.css" rel="stylesheet" type="text/css" />
<script src="your-library.js" type="text/javascript"></script>

The name pathToYourLibrary is defined in bundle.pathVarName (see Configuration Reference). By default it is the package name from the package.json converted into camel case (removing dashes, underscores, dots and tilde) and prefixed by pathTo. Please note the trailing slash that has to be defined.

Build Results of EJS Template HTML Files

If you need to write a HTML template you can set the end of the name of the HTML file *.ejs.html or *.template.html.

Files ending with *.ejs.html will be parsed by the package ejs. Files ending with *.template.html will be parsed by the underscore function template.

Then you can use variables like <%= locals["some-var"] %> in your template. All HTML templates will be included in the final JavaScript bundle

In your JavaScript file you require them and submit the properties of the variable data like this:

1
2
import htmlTemplate from "./path/to/your/file.ejs.html";
let resultingHtml = htmlTemplate({ "some-var": "some-value" });

To use the include methods of EJS you have to pay attention to this:

If you are using the ejs parser you cannot use the include() function. You have to use the include preprocessing statement:

1
<%- include inc/part.html %>

If you are using the template() function you have to include the content from variables like described here: Including nested templates:

index.js:

1
2
3
var mainTemplate = require("ejs!./main.ejs");
var hyperlinkTemplate = require("ejs!./hyperlink.ejs");
var renderedHtml = mainTemplate({ hyperlink: hyperlinkTemplate });

main.ejs:

1
<h1><%= hyperlink({ name: 'Example', url: 'http://example.com' }) %></h1>

hyperlink.ejs:

1
<a href="<%= url %>"><%= name %></a>

As a result, renderedHtml becomes a string <h1><a href="http://example.com">Example</a></h1>.

Build Result of Static Assets

All files within the folder static will be copied to the build result in the dist folder. Here is the best place to write your demo or test pages, your documentation or add some external assets.

The files inside of the folder inc will be ignored. You can add more filenames in staticParser.ignore (see Configuration Reference).

Note: The perfomance hints of webpack will be disabled for all files that will be copied from the dist folder.

Note: In the static folder you will find an file named index.html. If you delete this file and no other HTML file will is left, a default index.html file will be created in you dist folder.

The following files will be processed in a special way:

HTML Files

HTML files in this directory will be parsed and links to your final JavaScript and Stylesheet files and your external libraries will be injected as script and link tags. Furthermore the resulting HTML will be minified.

What HTML files exactly will be parsed is defined in staticParser.htmlTemplates (see Configuration Reference). By default all *.html files, except inside of the folder inc, will be parsed.

The tags will be placed in the head and body section. If you need to place them in other positions you must disable the inject feature in the staticParser.htmlInject (see Configuration Reference) and use the following placeholders:

1
2
<%- htmlWebpackPlugin.tags.headTags %>
<%- htmlWebpackPlugin.tags.bodyTags %>

You can include parts from other files with:

1
<%- include inc/part.html %>

Favicons

By default the file logo.png from the static folder will be converted in all possible favorite icons formats (android, appleIcon, appleStartup, coast, favicons, firefox, windows, yandex) and saved in a subdirectory named favicon. The necessary HTML will be injected into the HTML files (see above).

You can adjust the name of the file in staticParser.favicon (see Configuration Reference) or disable this feature complete if you set the field to null.

By default the source favicon file will be copied to the dist folder. If you do not need the file after favicon creation you can controll this behaviour in staticparser.keepFaviconSource (see Configuration Reference).

Build Results of External Libraries

To use external libraries you have to install them with npm install PACKAGENAME and import or require them in your code. Doing this the libraries will be included in your bundle. You should always consider to exclude them from your bundle and load them from a local file or a CDN.

Now you can do this in two ways:

(1) The very easy way:

Search a package in the package list of @cc-external. If you find your package there you can do just:

1
npm i @cc-external/PACKAGENAME

That's it. Your package is installed, you can use it and it will not be included into your bundle. Instead of this the needed assets will be copied into your dist/vendor folder and your HTML files will be injected with links to these assets. Furthermore you can build a version where the modules will not copied and the injected links will point to a CDN (see below "How to Build").

Note: Scoped packages like @fortawesome/fontawesome-free are written as fortawesome_fontawesome-free. So you would search for and install npm i @cc-external/fortawesome_fontawesome-free.

(2) The easy way:

Install the package on the classic way, create a file named webpack.externals.js in your project root directory and add there a definition for this package. This module exports an array of objects for every package you want to externalize. Every object need the following properties:

  • module: The name of the module (corresponds to the package name).
  • global: Optional. The global variable name to access the library provided by the node module.
  • entries: Optional. String or array of strings. Name of js or css files to copy from the modules folder to the dist folder and inject links to them into your HTML files.
  • copy: Optional. String or array of strings. Globs to copy from the modules folder to the dist folder. This can be used to copy assets like fonts.

Read more details here: The configuration file

With these configuration the library will not be included into your bundle. Instead of this the assets defined in entries and copy will be copied into your dist/vendor folder and your HTML files will be injected with links to these assets. Furthermore you can build a version where the modules will not copied and the injected links will point to a CDN (see below "How to Build").