Update docs for chai 5 - ESM

[schrotie]

As discussed here I open an issue for updating Chai's docs since Chai is now using ESMs exclusively and following the docs will break for people using it in a browser.

I've done a little work on that and created a patch. I don't fork and create a PR because I don't have a ruby environment set up and can thus not verify my changes. Github apparently does not support attaching *.patch here. Would you like me to paste the patch here?

[keithamus]

You can go ahead and paste the patch here, and we can look at applying it. Thanks!

[schrotie]

Okay, quick summary:

I stumbled upon the problem in the browser, so that's my perspective. I looked through https://www.chaijs.com/ and tried to find the stuff there in the source and fix it. I went through the guides. I also looked through the plugins, started, but realized that one needs to know the names of the exports of all the plugin. Fixing the plugins docs will be quite some work ...

I always use import {x} from 'chaijs' because I think that's cleaner. I think this works in node without additional hoop jumping but in the browser that requires building or an importmap which I documented in 'installation'. The alternative would be import {x} from ../node_modules/chai/chai.js` - and that path depends on where you are, or an absolute path depends on where your root is.

Related to this: I did not use the chai/register-should set up. It's possible (and easy) but requires additional set up in the importmap so I decided skipping the latter and instead adding a line for calling should() is simpler. However, for node-users chai/register-should would indeed still save a line, but I did not spend the thought on how to integrate that into the docs. See this comment.

Next comment is the patch.

Thanks for making and maintaining Chai!

[schrotie]

diff --git a/_guides/installation.md b/_guides/installation.md
index 167b47e..de6dd2b 100644
--- a/_guides/installation.md
+++ b/_guides/installation.md
@@ -39,18 +39,28 @@ which can be especially powerful when paired with a continuous integration tool.
 
 Include the chai browser build in your testing suite.
 
-```html
-<script src="chai.js" type="text/javascript"></script>
+```javascript
+import {assert, expect, should} from 'chai';
 ```
 
-This will provide `chai` as a global object, or `define` it if you are using AMD.
+This will provide chai's assertion utilities in your ESModule. You'll likely
+want to select one of these.
+
+If you are working in a browser without a build step, you'll need to tell the
+browser where to find chai, e.g.:
+
+```HTML
+<script type="importmap">{ "imports": {
+	"chai": "./node_modules/chai/chai.js"
+}}</script>
+```
 
 The latest tagged version will be available for hot-linking at [http://chaijs.com/chai.js]({{site.github.url}}/chai.js).
 If you prefer to host yourself, use the `chai.js` file from the root of the github project.
 We recommend that you always use a version tag as your starting point, so the
 [tag download list](https://github.com/chaijs/chai/tags) is the best place to start.
 
-Currently supports all modern browsers: IE 9+, Chrome 7+, FireFox 4+, Safari 5+. Please note
+Currently supports all modern browsers (if you use a build step): IE 9+, Chrome 7+, FireFox 4+, Safari 5+. Please note
 that the `should` style is currently not compatible with IE9.
 
 If you want to know if your browser is compatible, run the [online test suite]({{site.github.url}}/api/test/).
diff --git a/_guides/plugins.md b/_guides/plugins.md
index 8be2ae3..30a5d02 100644
--- a/_guides/plugins.md
+++ b/_guides/plugins.md
@@ -30,7 +30,8 @@ by using the `use` method of the chai export, which accepts a single function as
 an argument.
 
 ```javascript
-chai.use(function (_chai, utils) {
+import {use} from 'chai'
+use(function (_chai, utils) {
   // ...
 });
 ```
@@ -46,9 +47,8 @@ community. A more appropriate pattern for creating helpers is as follows...
 For our helper file: `test/helpers/model.js`
 
 ```javascript
-module.exports = function (chai, utils) {
-  var Assertion = chai.Assertion;
-
+import {Assertion} from 'chai'
+export function chaiModel(chai, utils) {
   // your helpers here
 };
 ```
@@ -56,11 +56,10 @@ module.exports = function (chai, utils) {
 And, for our actual test: `test/person.js`
 
 ```javascript
-var chai = require('chai')
-  , chaiModel = require('./helpers/model')
-  , expect = chai.expect;
+import {expect, use} from 'chai'
+import {chaiModel} from './helpers/model'
 
-chai.use(chaiModel);
+use(chaiModel);
 ```
 
 For the rest of this document, we will assume this structure...
diff --git a/_guides/styles.md b/_guides/styles.md
index de9a264..1859753 100644
--- a/_guides/styles.md
+++ b/_guides/styles.md
@@ -28,8 +28,8 @@ node.js. This assert module, however, provides several additional
 tests and is browser compatible.
 
 ```js
-var assert = require('chai').assert
-  , foo = 'bar'
+import {assert} from 'chai'
+var foo = 'bar'
   , beverages = { tea: [ 'chai', 'matcha', 'oolong' ] };
 
 assert.typeOf(foo, 'string'); // without optional message
@@ -59,8 +59,8 @@ The BDD style is exposed through `expect` or `should` interfaces. In both
 scenarios, you chain together natural language assertions.
 
 ```js
-var expect = require('chai').expect
-  , foo = 'bar'
+import {expect} from 'chai'
+var foo = 'bar'
   , beverages = { tea: [ 'chai', 'matcha', 'oolong' ] };
 
 expect(foo).to.be.a('string');
@@ -94,8 +94,9 @@ property to start your chain. This style has some issues when used with Internet
 Explorer, so be aware of browser compatibility.
 
 ```js
-var should = require('chai').should() //actually call the function
-  , foo = 'bar'
+import {should} from 'chai'
+should()
+var foo = 'bar'
   , beverages = { tea: [ 'chai', 'matcha', 'oolong' ] };
 
 foo.should.be.a('string');
@@ -106,14 +107,13 @@ beverages.should.have.property('tea').with.lengthOf(3);
 
 ### Differences
 
-First of all, notice that the `expect` require is just a reference to the
-`expect` function, whereas with the `should` require, the function is
-being executed.
+First of all, notice that `assert`and `expect` are references to the
+respective functions, whereas with the `should`, the function is
+being executed to set up the leading `should` in your assertion chains.
 
 ```js
-var chai = require('chai')
-  , expect = chai.expect
-  , should = chai.should();
+import {expect, should} from 'chai'
+should()
 ```
 
 The `expect` interface provides a function as a starting point for chaining
@@ -143,7 +143,8 @@ with a `should` chain starter. As such, the appropriate few assertions
 for this scenario are as follows:
 
 ```js
-var should = require('chai').should();
+import {should} from 'chai'
+should()
 db.get(1234, function (err, doc) {
   should.not.exist(err);
   should.exist(doc);
@@ -161,22 +162,6 @@ quick helpers to keep you out of trouble when using `should`.
 - `should.Throw`
 - `should.not.Throw`
 
-### Using Should in ES2015
-
-It isn't possible to chain a function call from an ES2015 `import`
-statement – it has to go on its own line, which looks a little
-verbose:
-
-```js
-import chai from 'chai';
-chai.should();
-```
-
-For a cleaner look, you can do this instead:
-
-```js
-import 'chai/register-should';
-```
 
 ## Configuration
 
@@ -190,7 +175,8 @@ Assertion error message. Default of `false` suppresses stack trace in the error
 message.
 
 ```javascript
-chai.config.includeStack = true; // turn on stack trace
+import {config} from 'chai'
+config.includeStack = true; // turn on stack trace
 ```
 
 ### config.showDiff
@@ -203,7 +189,8 @@ should be included in the thrown AssertionErrors. `false` will always be `false`
 `true` will be true when the assertion has requested a diff be shown.
 
 ```javascript
-chai.config.showDiff = false; // turn off reporter diff display
+import {config} from 'chai'
+config.showDiff = false; // turn off reporter diff display
 ```
 
 ### config.truncateThreshold
@@ -217,5 +204,6 @@ in assertion errors. If this threshold is exceeded, the value is truncated.
 Set it to zero if you want to disable truncating altogether.
 
 ```javascript
-chai.config.truncateThreshold = 0; // disable truncating
+import {config} from 'chai'
+config.truncateThreshold = 0; // disable truncating
 ```
diff --git a/index.html b/index.html
index 96895dc..5ad5541 100644
--- a/index.html
+++ b/index.html
@@ -18,7 +18,8 @@ includeBanner: true
               <h3 class="fancy">Should</h2>
               <div class="code-sample">
                 {% highlight js %}
-chai.should();
+import {should} from 'chai';
+should();
 
 foo.should.be.a('string');
 foo.should.equal('bar');
@@ -38,7 +39,7 @@ tea.should.have.property('flavors')
               <h3 class="fancy">Expect</h2>
               <div class="code-sample">
                 {% highlight js %}
-var expect = chai.expect;
+import {expect} from 'chai';
 
 expect(foo).to.be.a('string');
 expect(foo).to.equal('bar');
@@ -58,7 +59,7 @@ expect(tea).to.have.property('flavors')
               <h3 class="fancy">Assert</h2>
               <div class="code-sample">
                 {% highlight js %}
-var assert = chai.assert;
+import {assert} from 'chai';
 
 assert.typeOf(foo, 'string');
 assert.equal(foo, 'bar');