Directory structure

[joyeecheung]

Inspired by https://github.com/nodejs/node-addon-examples/ I think it would be nice to have a directory structure like this:

- examples
    - 1-simple-cjs-only
    - 2-simple-esm-only
    - 3-write-cjs-support-both-directly
    - 4-write-esm-support-both-directly
    - 5-write-esm-distribute-cjs
    - ...
- guide  # a minibook on how to ship packages, published to GitHub pages for better SEO

The guide can point to the examples to better show how they are supposed to look. We can have some workflows and tests to check that the examples work properly, and can even publish them to npm to verify that they work.

[joyeecheung]

So I played a bit with honkit (fork of Gitbook) and came up with this structure for the guide, taking some inspiration from https://hirok.io/posts/package-json-exports , the bits moved here, and nodejs/nodejs.org#7229

# Node.js package configuration guide

### Getting started

* [Primer on `package.json`](01-getting-started/package-json-fields.md)
* [CommonJS and ESM](01-getting-started/commonjs-and-esm.md)

### Basics

* [Single file package configurations](02-single-file-package/README.md)
    * [Classic CommonJS package](02-single-file-package/classic-commonjs/README.md)
    * [Simple ESM package](02-single-file-package/simple-esm/README.md)
* [Multi-file package configurations](03-multi-file-package/README.md)
    * [`"exports"` field](03-multi-file-package/exports-field.md)
    * [`"files"` field](03-multi-file-package/files-field.md)
    * [Examples](03-multi-file-package/examples/README.md)
* [CommonJS and ESM interoperability](04-cjs-esm-interop/README.md)
    * [Making CommonJS importable](04-cjs-esm-interop/import-cjs/README.md)
    * [Making ESM require-able](04-cjs-esm-interop/require-esm/README.md)

### Packages with a build step

* [Bundling](05-bundling/README.md)
    * [Bundling with Webpack](05-bundling/bundling-with-webpack/README.md)
    * [Other bundlers](05-bundling/other-bundlers.md)
    * [Source maps](05-bundling/sourcemaps/README.md)
* [Dual packages](06-dual-packages/README.md)
    * [History of dual packages](06-dual-packages/dual-package-history.md)
    * [Dual package hazards](06-dual-packages/dual-package-hazards.md)
    * [Two full distributions](06-dual-packages/two-full-distributions/README.md)
    * [CommonJS distribution, ESM wrapper](06-dual-packages/esm-wrapper/README.md)
* [Package configuration tools](07-package-config-tools/README.md)

---

* [Q&A](q-n-a/README.md)
* [Troubleshooting](troubleshooting/README.md)

Which generates something like this:

After looking into it a bit I think it might be nicer to directly embed examples into guide directories? So for example, 02-single-file-package/classic-commonjs/ is going to directly contain a working example, while the README.md which contains information about how it works serves as a README. Another idea that I think would be useful is, at the end of each example's README, list certain versions of popular packages that use the documented patterns, for readers to check out what it looks like in a real-world package, and extrapolate to their own packages.

I feel that at some point, after the experimental TypeScript support becomes stable, we should also add a chapter about configuring a package written in TypeScript, but it's probably still too early at this point as the core decisions about how this is supposed to work is still a bit in the air.

Another topic that might be interesting is how to configure a package properly for tree-shaking/code bundled to run both in browsers and on servers. Though I am not sure if this is the right place to document them. Can be a stretch goal for now.

[joyeecheung]

Opened #6 to get it going.