Skip to content
This repository was archived by the owner on Aug 16, 2025. It is now read-only.

Commit 245d921

Browse files
jaredcwhitejaredcwhite
authored
MIGRATED to Codeberg
1 parent 389d25b commit 245d921

File tree

1 file changed

+2
-131
lines changed

1 file changed

+2
-131
lines changed

‎README.md

Lines changed: 2 additions & 131 deletions
Original file line numberDiff line numberDiff line change
@@ -1,133 +1,4 @@
11
# esbuild-plugin-html-modules
22

3-
[![npm][npm]][npm-url]
4-
[![CI Test](https://github.com/whitefusionhq/esbuild-plugin-html-modules/actions/workflows/ci.yml/badge.svg)](https://github.com/whitefusionhq/esbuild-plugin-html-modules/actions/workflows/ci.yml)
5-
6-
7-
An esbuild plugin to load HTML Modules. [This is a proposed spec](https://github.com/WICG/webcomponents/blob/gh-pages/proposals/html-modules-explainer.md) defined here by [@dandclark](https://github.com/dandclark) which would allow HTML files to be exported and importable as ES modules where the HTML itself is transformed into an exported HTML template and a `<script type="module">` tag is run as the JavaScript of the module. The template is available from inside the module script code via `import.meta.document`, and externally as the default ES export of the file.
8-
9-
An HTML module could look like this:
10-
11-
```html
12-
<script type="module">
13-
export const hello = () => {
14-
return import.meta.document.querySelector("h1")
15-
}
16-
</script>
17-
18-
<h1>Hello World</h1>
19-
20-
<p>Everything here is included in the default document export.</p>
21-
```
22-
23-
And you could import it like this:
24-
25-
```js
26-
// in some JS file:
27-
28-
import HelloWorld, { hello } from "src/hello-world.html" with { type: "html" }
29-
30-
console.log(hello())
31-
32-
console.log(HelloWorld.querySelector("p"))
33-
```
34-
35-
## Install
36-
37-
```sh
38-
npm install esbuild-plugin-html-modules -D
39-
```
40-
41-
```sh
42-
yarn add esbuild-plugin-html-modules -D
43-
```
44-
45-
## Usage
46-
47-
Add the plugin to your esbuild config file. For example:
48-
49-
```js
50-
const esbuild = require('esbuild')
51-
const htmlModulesPlugin = require('esbuild-plugin-html-modules')
52-
53-
esbuild.build({
54-
bundle: true,
55-
entryPoints: ['src/index.js'],
56-
outfile: 'dist/index.js',
57-
plugins: [
58-
htmlModulesPlugin()
59-
]
60-
}).catch(() => process.exit(1))
61-
```
62-
63-
You can also pass a specific filter in if you wish to support only specific extensions, like `.module.html` or `.mod.html`, in your project:
64-
65-
```js
66-
plugins: [
67-
htmlModulesPlugin({ filter: /\.mod\.html$/ })
68-
]
69-
```
70-
71-
Now you'll be able to import HTML modules. Take a peek at the [files in the `test/fixture` folder](https://github.com/whitefusionhq/esbuild-plugin-html-modules/tree/main/test/fixture) for an example of how this could work.
72-
73-
Other configuration options are contained within the `experimental` section because they go beyond the proposed spec to offer some helpful features. Here's an example:
74-
75-
```js
76-
const postcssrc = require("postcss-load-config")
77-
const postcss = require("postcss")
78-
79-
80-
// later in the esbuild config:
81-
82-
htmlModulesPlugin({
83-
experimental: {
84-
extractGlobalStyles: true,
85-
exportLocalStylesExtension: "css-local",
86-
ignoreSSROnly: true,
87-
transformLocalStyles: async (css, { filePath }) => {
88-
const postCssConfig = await postcssrc()
89-
const postCssProcessor = postcss([...postCssConfig.plugins])
90-
91-
const results = await postCssProcessor.process(css, { ...postCssConfig.options, from: filePath })
92-
return results.css
93-
}
94-
}
95-
})
96-
```
97-
98-
## Transforming Styles
99-
100-
> [!WARNING]
101-
> The `extractScopedStyles: true` experimental option was removed in v0.8. We recommend you use the usual CSS nesting—or soon, the newer `@scope` standard—in a global stylesheet if you want to author "scoped" light DOM styles.
102-
103-
If you define `extractGlobalStyles: true`, then any `style` tag featuring a `scope="global"` attribute or a `global` boolean attribute will have those styles extracted out of there and included in esbuild's CSS bundle output.
104-
105-
If you define a `transformLocalStyles` function, then any local style tag contained within your HTML (not explicitly scoped) will have its contents transformed by the function. Above you can see this done using PostCSS, but you could use another processor such as Sass if you prefer. This is useful for style tags which get included in shadow DOM templates (and you wouldn't want to include those styles in the CSS bundle).
106-
107-
## Bundling Lifecycle
108-
109-
As part of transforming local styles, you can optionally export those transformed styles into "sidecar" CSS output file. This can be helpful if you would like another process to use those styles in SSR. By setting the `exportLocalStylesExtension` option, a file with the provided extension will be saved right alongside the HTML module. **Note:** it's highly recommended you add that extension to your `.gitignore` file as they're purely build-time automated.
110-
111-
For controlling the bundling characteristics of "split" components where some (or all!) functionality is server-only, you can set the `ignoreSSROnly` option to `true`. This will then filter out (aka remove) any elements in the module with a `data-ssr-only` attribute present. For example, you could have a `template` tag, `script` tag, and `style` tag which _all_ feature `data-ssr-only`, and therefore the bundled module would export a blank fragment. This technique can work well for "resumable" components which don't require access to the full module template at client-side runtime.
112-
113-
**Note:** this does _not_ skip the styles processing. Any local style tags will still be transformed if those options have been set, and any scoped or global styles will be extracted if those options have been set.
114-
115-
## Testing
116-
117-
Run:
118-
119-
```sh
120-
npm run test
121-
```
122-
123-
## Contributing
124-
125-
1. Fork it (https://github.com/whitefusionhq/esbuild-plugin-html-modules/fork)
126-
2. Clone the fork using `git clone` to your local development machine.
127-
3. Create your feature branch (`git checkout -b my-new-feature`)
128-
4. Commit your changes (`git commit -am 'Add some feature'`)
129-
5. Push to the branch (`git push origin my-new-feature`)
130-
6. Create a new Pull Request
131-
132-
[npm]: https://img.shields.io/npm/v/esbuild-plugin-html-modules.svg
133-
[npm-url]: https://npmjs.com/package/esbuild-plugin-html-modules
3+
> [!CAUTION]
4+
> This project [has migrated to Codeberg](https://codeberg.org/jaredwhite/esbuild-plugin-html-modules). Please update your references accordingly and do not link to this GitHub project. It has now been archived. Thank you!

0 commit comments

Comments
 (0)