Skip to content

Commit e42dae5

Browse files
authored
(docs) add usage of ES6 Modules in browser (#4099)
1 parent a7685d2 commit e42dae5

File tree

1 file changed

+62
-9
lines changed

1 file changed

+62
-9
lines changed

README.md

Lines changed: 62 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -41,14 +41,15 @@ detection.
4141
- [Using with Vue.js](#using-with-vuejs)
4242
- [Using Web Workers](#using-web-workers)
4343
- [Importing the Library](#importing-the-library)
44-
- [Node.js / `require`](#nodejs--require)
45-
- [ES6 Modules / `import`](#es6-modules--import)
44+
- [Node.js CommonJS Modules / `require`](#nodejs-commonjs-modules--require)
45+
- [Node.js ES6 Modules / `import`](#nodejs-es6-modules--import)
46+
- [Browser ES6 Modules](#browser-es6-modules)
4647
- [Getting the Library](#getting-the-library)
4748
- [Fetch via CDN](#fetch-via-cdn)
4849
- [cdnjs (link)](#cdnjs-link)
4950
- [jsdelivr (link)](#jsdelivr-link)
5051
- [unpkg (link)](#unpkg-link)
51-
- [Download prebuilt CDN assets](#download-prebuilt-cdn-assets)
52+
- [Download prebuilt CDN assets](#download-prebuilt-cdn-assets)
5253
- [Download from our website](#download-from-our-website)
5354
- [Install via NPM package](#install-via-npm-package)
5455
- [Build from Source](#build-from-source)
@@ -240,7 +241,7 @@ onmessage = (event) => {
240241
First, you'll likely be installing the library via `npm` or `yarn` -- see [Getting the Library](#getting-the-library).
241242

242243

243-
### Node.js / `require`
244+
### Node.js CommonJS Modules / `require`
244245

245246
Requiring the top-level library will load all languages:
246247

@@ -266,10 +267,7 @@ const highlightedCode = hljs.highlight('<span>Hello World!</span>', {language: '
266267
```
267268

268269

269-
### ES6 Modules / `import`
270-
271-
*Note: You can also import directly from fully static URLs, such as our very own pre-built
272-
ES6 Module CDN resources. See [Fetch via CDN](#fetch-via-cdn) for specific examples.*
270+
### Node.js ES6 Modules / `import`
273271

274272
The default import will register all languages:
275273

@@ -292,6 +290,53 @@ import hljs from 'highlight.js';
292290
import 'highlight.js/styles/github.css';
293291
```
294292

293+
### Browser ES6 Modules
294+
295+
*Note: For now you'll want to install `@highlightjs/cdn-assets` package instead of `highlight.js`.
296+
See [Download prebuilt CDN assets](#download-prebuilt-cdn-assets)*
297+
298+
To import the library and register only those languages that you need:
299+
300+
```js
301+
import hljs from './assets/js/@highlightjs/cdn-assets/es/core.js';
302+
import javascript from './assets/js/@highlightjs/cdn-assets/es/languages/javascript.min.js';
303+
304+
hljs.registerLanguage('javascript', javascript);
305+
```
306+
307+
To import the library and register all languages:
308+
309+
```js
310+
import hljs from './assets/js/@highlightjs/cdn-assets/es/highlight.js';
311+
```
312+
313+
*Note: The path to these files will vary depending on where you have installed/copied them
314+
within your project or site. The above path is only an example.*
315+
316+
You can also use [`importmap`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap) to import in similar way as Node:
317+
318+
```html
319+
<script type="importmap">
320+
{
321+
"imports": {
322+
"@highlightjs": "./assets/js/@highlightjs/cdn-assets/es/"
323+
}
324+
}
325+
</script>
326+
```
327+
328+
Use the above code in your HTML. After that, your JavaScript can import using the named key from
329+
your `importmap`, for example `@highlightjs` in this case:
330+
331+
```js
332+
import hljs from '@highlightjs/core.js';
333+
import javascript from '@highlightjs/languages/javascript.min.js';
334+
335+
hljs.registerLanguage('javascript', javascript);
336+
```
337+
338+
*Note: You can also import directly from fully static URLs, such as our very own pre-built ES6 Module CDN resources. See [Fetch via CDN](#fetch-via-cdn) for specific examples.*
339+
295340

296341
## Getting the Library
297342

@@ -395,7 +440,7 @@ hljs.registerLanguage('go', go);
395440
**Note:** *The CDN-hosted `highlight.min.js` package doesn't bundle every language.* It would be
396441
very large. You can find our list of "common" languages that we bundle by default on our [download page][5].
397442

398-
#### Download prebuilt CDN assets
443+
### Download prebuilt CDN assets
399444

400445
You can also download and self-host the same assets we serve up via our own CDNs. We publish those builds to the [cdn-release](https://github.com/highlightjs/cdn-release) GitHub repository. You can easily pull individual files off the CDN endpoints with `curl`, etc; if say you only needed `highlight.min.js` and a single CSS file.
401446

@@ -418,6 +463,14 @@ npm install highlight.js
418463
yarn add highlight.js
419464
```
420465

466+
There is also another npm package [@highlightjs/cdn-assets](https://www.npmjs.com/package/@highlightjs/cdn-assets) that contains prebuilt CDN assets including [ES6 Modules that can be imported in browser](#browser-es6-modules):
467+
468+
```bash
469+
npm install @highlightjs/cdn-assets
470+
# or
471+
yarn add @highlightjs/cdn-assets
472+
```
473+
421474
Alternatively, you can build the NPM package from source.
422475

423476

0 commit comments

Comments
 (0)