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.
If running the DevServer will watch all the used files in the src
directory and all changes in the
static
folder (modifying, adding, deleting files) 1. Changes will trigger a rebuild and full
page reload.
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 |
|
Load them dynamically from separate files
You can use the following syntax to load an HTML file dynamically:
1 2 3 |
|
- 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 |
|
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 |
|
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 |
|
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 |
|
main.ejs:
1 |
|
hyperlink.ejs:
1 |
|
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 |
|
You can include parts from other files with:
1 |
|
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 |
|
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 each package you want to externalize. Each 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
orcss
files to copy from the modules folder to thedist
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").
-
Watching of changes in the
static
folder only works from version 2.4 upwards. ↩