Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Added some documentation about the ESM usage
  • Loading branch information
cedx committed Jul 9, 2019
1 parent 10a6164 commit f1b3c64
Show file tree
Hide file tree
Showing 2 changed files with 40 additions and 0 deletions.
39 changes: 39 additions & 0 deletions doc/esm.md
@@ -0,0 +1,39 @@
# ESM Upgrade Path
As of version 10, this plug-in uses the syntax of [ECMAScript modules](https://nodejs.org/api/esm.html). This is a major change: your [Gulp](https://gulpjs.com) script will not work as usual.

If you don't modify it, you will see this kind of errors:

```
SyntaxError: Unexpected token {
```

You have 2 choices:

- continue to use version 9: as long as ES modules are marked as experimental, this is the recommended solution.
- port your Gulp script to ES modules.

If you choose the second option, here are the steps to follow.

## Install the `esm` package
Gulp does not natively support ES modules, but it is able to work with them thanks to the [`esm` package](https://www.npmjs.com/package/esm). Modify your project to add this additional dependency:

```shell
npm install --save-dev esm
```

## Rewrite your Gulp script
In order for Gulp to recognize that you are using ES modules, you must rename your `gulpfile.js` file to` gulpfile.esm.js`.

Then, all you have to do is rewrite the `require` statements as `import` ones.

```js
// Before: CommonJS syntax.
const gulp = require('gulp');
const {phpMinify} = require('@cedx/gulp-php-minify');

// After: ESM syntax.
import gulp from 'gulp';
import {phpMinify} from '@cedx/gulp-php-minify';
```

That's it!
1 change: 1 addition & 0 deletions etc/mkdocs.yaml
Expand Up @@ -30,6 +30,7 @@ nav:
- Overview: index.md
- Installation: installation.md
- Usage: usage.md
- ESM upgrade path: esm.md
- About:
- Changelog: about/changelog.md
- License: about/license.md
Expand Down

0 comments on commit f1b3c64

Please sign in to comment.