Skip to content

Commit 4732af5

Browse files
webdiscuswebdiscus
committed
chore: add example for usage with RSPack, still yet not supported
1 parent 82aad83 commit 4732af5

7 files changed

Lines changed: 5006 additions & 8 deletions

File tree

‎README.md‎

Lines changed: 134 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -494,6 +494,8 @@ See [boilerplate](https://github.com/webdiscus/webpack-html-scss-boilerplate)
494494
- [How to inline SVG, PNG images in HTML](#recipe-inline-image)
495495
- [How to resolve source assets in an attribute containing JSON value](#recipe-resolve-attr-json)
496496
- [How to load CSS file dynamically](#recipe-dynamic-load-css)
497+
- [How to load JS and CSS from `node_modules` in template](#recipe-load-js-css-from-node-modules)
498+
- [How to import CSS or SCSS from `node_modules` in SCSS](#recipe-import-style-from-node-modules)
497499
- [How to process a PHP template](#recipe-preprocessor-php)
498500
- [How to pass data into multiple templates](#recipe-pass-data-to-templates)
499501
- [How to use some different template engines](#recipe-diff-templates)
@@ -502,6 +504,7 @@ See [boilerplate](https://github.com/webdiscus/webpack-html-scss-boilerplate)
502504
- [How to split CSS files](#recipe-split-css)
503505
2. [Problems & Solutions](#solutions)
504506
- [Automatic resolving of file extensions](#solutions-resolve-extensions)
507+
- [How to use `@import url()` in CSS](#solutions-import-url-in-css)
505508
3. <a id="demo-sites" name="demo-sites"></a>
506509
Demo sites
507510
- Multiple page e-shop template (`Handlebars`) [demo](https://alpine-html-bootstrap.vercel.app/) | [source](https://github.com/webdiscus/demo-shop-template-bundler-plugin)
@@ -530,15 +533,15 @@ See [boilerplate](https://github.com/webdiscus/webpack-html-scss-boilerplate)
530533
- [extracts JS](#option-js) from the source script filename specified in HTML via a `<script>` tag
531534
- [extracts CSS](#option-css) from the source style filename specified in HTML via a `<link>` tag
532535
- importing style files in JavaScript
533-
- resolves source asset files in HTML attributes and in the CSS `url()`
536+
- resolves source asset files in HTML attributes and in the CSS `url()`, without using [resolve-url-loader](https://github.com/bholloway/resolve-url-loader)
534537
- supports styles used in `*.vue` files
535538
- generated HTML contains output filenames
536539
- supports the module types `asset/resource` `asset/inline` `asset` `asset/source` ([\*](#note-asset-source))
537540
- [inline CSS](#recipe-inline-css) in HTML
538541
- [inline JavaScript](#recipe-inline-js) in HTML
539542
- [inline image](#recipe-inline-image) as `base64 encoded` data-URL for PNG, JPG, etc. in HTML and CSS
540-
- [inline SVG](#recipe-inline-image) as SVG tag in HTML
541-
- [inline SVG](#recipe-inline-image) as `utf-8` data-URL in CSS
543+
- [inline SVG](#recipe-inline-image) as SVG tag in HTML, e.g.: `<svg>...</svg>`
544+
- [inline SVG](#recipe-inline-image) as `utf-8` data-URL in CSS, e.g.: `url("data:image/svg+xml,<svg>...</svg>")`
542545
- auto generation of `<link rel="preload">` to [preload assets](#option-preload)
543546
- supports the `auto` [publicPath](#webpack-option-output-publicpath)
544547
- enable/disable [extraction of comments](#option-extract-comments) to `*.LICENSE.txt` file
@@ -5173,8 +5176,96 @@ loadCSS(cssFile);
51735176
51745177
The CSS will be extracted into separate file and the `cssFile` variable will contains the CSS output filename.
51755178
5179+
#### [↑ back to contents](#contents)
51765180
5177-
---
5181+
5182+
<a id="recipe-load-js-css-from-node-modules" name="recipe-load-js-css-from-node-modules"></a>
5183+
## How to load JS and CSS from `node_modules` in template
5184+
5185+
Some node modules specifies compiled bundle files for the browser in `package.json`.
5186+
5187+
For example:
5188+
- the [material-icons](https://github.com/marella/material-icons/blob/main/package.json) specifies the `browser ready` CSS file.
5189+
- the [bootstrap](https://github.com/twbs/bootstrap/blob/main/package.json) specifies the `browser ready` JS and CSS files.
5190+
5191+
You can use only the module name, the plugin automatically resolves `browser ready` files for script and style:
5192+
5193+
```html
5194+
<html>
5195+
<head>
5196+
<!-- plugin resolves the bootstrap/dist/css/bootstrap.css -->
5197+
<link href="bootstrap" rel="stylesheet">
5198+
<!-- plugin resolves the bootstrap/dist/js/bootstrap.js -->
5199+
<script src="bootstrap" defer="defer"></script>
5200+
</head>
5201+
<body>
5202+
<h1>Hello World!</h1>
5203+
</body>
5204+
</html>
5205+
```
5206+
5207+
If you need to load a specific version of a file, use the module name and the path to that file:
5208+
5209+
```html
5210+
<html>
5211+
<head>
5212+
<link href="bootstrap/dist/css/bootstrap.rtl.css" rel="stylesheet">
5213+
<script src="bootstrap/dist/js/bootstrap.bundle.js" defer="defer"></script>
5214+
</head>
5215+
<body>
5216+
<h1>Hello World!</h1>
5217+
</body>
5218+
</html>
5219+
```
5220+
5221+
> **Warning**
5222+
>
5223+
> Don't use a relative path to `node_modules`, like `../node_modules/bootstrap`. The plugin resolves node module path by the name automatically.
5224+
5225+
#### [↑ back to contents](#contents)
5226+
5227+
5228+
<a id="recipe-import-style-from-node-modules" name="recipe-import-style-from-node-modules"></a>
5229+
## How to import CSS or SCSS from `node_modules` in SCSS
5230+
5231+
The plugin resolves default style files defined in node_modules automatically.
5232+
5233+
For example, import source styles of material-icons:
5234+
5235+
```scss
5236+
// import source styles from `material-icons` module
5237+
@use 'material-icons';
5238+
5239+
// define short class name for original `.material-icons-outlined` class name from module
5240+
.mat-icon {
5241+
@extend .material-icons-outlined;
5242+
}
5243+
```
5244+
5245+
You can import a file from a module using the module name and the path to the file:
5246+
```scss
5247+
@use 'MODULE_NAME/path/to/style';
5248+
```
5249+
5250+
> **Warning**
5251+
>
5252+
> The file extension, e.g. .scss, .css, must be omitted.
5253+
5254+
> **Warning**
5255+
>
5256+
> Use the `@use` instead of `@import`, because it is [deprecated](https://github.com/sass/sass/blob/main/accepted/module-system.md#timeline).
5257+
5258+
5259+
For example, import the style theme `tomorrow` from the [prismjs](https://github.com/PrismJS/prism) module:
5260+
```scss
5261+
@use 'prismjs/themes/prism-tomorrow.min';
5262+
```
5263+
5264+
> **Warning**
5265+
>
5266+
> Don't use [resolve-url-loader](https://github.com/bholloway/resolve-url-loader)!
5267+
>
5268+
> The HTML bundler plugin resolves styles faster than `resolve-url-loader` and don't requires using the `source map` in `sass-loader` options.
51785269
51795270
#### [↑ back to contents](#contents)
51805271
@@ -5855,10 +5946,48 @@ import moduleB from './moduleB';
58555946
import './app.scss'; // <= use the style extension
58565947
```
58575948
5858-
---
5949+
#### [↑ back to contents](#contents)
5950+
5951+
5952+
<a id="solutions-import-url-in-css" name="solutions-import-url-in-css"></a>
5953+
5954+
## How to use `@import url()` in CSS
5955+
5956+
> **Warning**
5957+
>
5958+
> Don't use `@import in CSS`. It's very `bad practice`.
5959+
>
5960+
5961+
Bad example, _main.css_:
5962+
```css
5963+
@import 'path/to/style.css';
5964+
```
5965+
5966+
The plugin does not support handling of `@import url()` in CSS. Imported url will be passed 1:1 into resulting CSS.
5967+
5968+
**Problem:** defaults, `css-loader` handles `@import at-rule`, which causes an issue in the plugin.
5969+
5970+
**Solution:** add the `import: false` into `css-loader` options:
5971+
5972+
```js
5973+
{
5974+
test: /\.(css)$/i,
5975+
loader: 'css-loader',
5976+
options: {
5977+
import: false, // disable handling of @import at-rule in CSS
5978+
},
5979+
},
5980+
```
5981+
5982+
> **Warning**
5983+
>
5984+
> The `*.css` files imported in CSS are not handled, therefore these files must be manually copied to the `dist/` folder using the `copy-webpack-plugin`.
58595985
58605986
#### [↑ back to contents](#contents)
58615987
5988+
---
5989+
5990+
58625991
## Also See
58635992
58645993
- [ansis][ansis] - The Node.js lib for ANSI color styling of text in terminal

‎experiments/rspack/README.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# RSPack and HTML Bundler
2+
3+
A symbiosis of the fast RSPack and the powerful [html-bundler-webpack-plugin](https://github.com/webdiscus/html-bundler-webpack-plugin) could be a `Vite` killer.
4+
5+
But currently RSPack `v0.5.6` is yet not 100% compatible with the Webpack.
6+
7+
Using the `html-bundler-webpack-plugin` with `RSPack` occurs the issue:
8+
9+
```
10+
/Users/xxxx/html-bundler-webpack-plugin/experiments/rspack/node_modules/@rspack/core/dist/Compiler.js:518
11+
__classPrivateFieldSet(this, _Compiler_instance, new instanceBinding.Rspack(rawOptions, this.builtinPlugins, {
12+
^
13+
14+
Error: Failed to convert JavaScript value `function filenameFn(..) ` into rust type `String`
15+
16+
at Compiler._Compiler_getInstance (/Users/xxxx/html-bundler-webpack-plugin/experiments/rspack/node_modules/@rspack/core/dist/Compiler.js:518:54)
17+
at Compiler.build (/Users/xxxx/html-bundler-webpack-plugin/experiments/rspack/node_modules/@rspack/core/dist/Compiler.js:384:87)
18+
at /Users/xxxx/html-bundler-webpack-plugin/experiments/rspack/node_modules/@rspack/core/dist/Watching.js:263:23
19+
at Hook.eval [as callAsync] (eval at create (/Users/xxxx/html-bundler-webpack-plugin/experiments/rspack/node_modules/tapable/lib/HookCodeFactory.js:33:10), <anonymous>:24:1)
20+
at Hook.CALL_ASYNC_DELEGATE [as _callAsync] (/Users/xxxx/html-bundler-webpack-plugin/experiments/rspack/node_modules/tapable/lib/Hook.js:18:14)
21+
at Watching._Watching_go (/Users/xxxx/html-bundler-webpack-plugin/experiments/rspack/node_modules/@rspack/core/dist/Watching.js:253:34)
22+
at Watching._Watching_invalidate (/Users/xxxx/html-bundler-webpack-plugin/experiments/rspack/node_modules/@rspack/core/dist/Watching.js:217:74)
23+
at /Users/xxxx/html-bundler-webpack-plugin/experiments/rspack/node_modules/@rspack/core/dist/Watching.js:51:94
24+
at process.processTicksAndRejections (node:internal/process/task_queues:77:11) {
25+
code: 'GenericFailure'
26+
}
27+
```
28+
29+
## Environment
30+
31+
- macOS 14.4 (23E214)
32+
- version of Node.js: v18.18.2
33+
- version of RSPack: 0.5.6
34+
- version of Webpack: 5.90.3
35+
- version of the HTML Bundler Plugin: 3.6.1
36+
37+
## How to reproduce
38+
39+
```
40+
npm i
41+
npm run dev
42+
```

0 commit comments

Comments
 (0)