| 1 | <br />
|
| 2 | <br />
|
| 3 |
|
| 4 | <div align="center">
|
| 5 | <img src="https://raw.githubusercontent.com/natemoo-re/microsite/master/.github/assets/microsite.svg?sanitize=true&v=1" alt="microsite" width="375" height="101" />
|
| 6 | </div>
|
| 7 |
|
| 8 | <h4 align="center">
|
| 9 | <a href="https://github.com/natemoo-re/microsite/tree/main/docs">Read the docs</a>
|
| 10 | <span> | </span>
|
| 11 | <a href="https://examples.microsite.page">See the live examples</a>
|
| 12 | <span> | </span>
|
| 13 | <a href="https://discord.gg/QMc6R8svPY">Join our Discord</a>
|
| 14 | </h4>
|
| 15 |
|
| 16 | <br />
|
| 17 | <br />
|
| 18 |
|
| 19 | `microsite` is a fast, opinionated static-site generator (SSG) built on top of [Snowpack](https://snowpack.dev). It outputs extremely minimal clientside code using [**automatic partial hydration**](https://github.com/natemoo-re/microsite/blob/main/docs/basic/bundled-javascript.md#automatic-partial-hydration).
|
| 20 |
|
| 21 | ```bash
|
| 22 | npm init microsite
|
| 23 | ```
|
| 24 |
|
| 25 | ---
|
| 26 |
|
| 27 | Microsite's public API is quite stable, but I caution **professional users** to consider this a WIP! There are plenty of quirks and bugs (especially with `dev` mode) that are being ironed out until Microsite reaches a more stable v2.0.0!
|
| 28 |
|
| 29 | ---
|
| 30 |
|
| 31 | Microsite is an **ESM node package**, so it needs to run in a Node environment which supports ESM. We support the latest version of [`node` v12.x LTS (Erbium)](https://nodejs.org/download/release/latest-v12.x/) — see [Engines](https://github.com/natemoo-re/microsite/blob/main/docs/engines.md) for more details.
|
| 32 |
|
| 33 | Ensure that your project includes `"type": "module"` in `package.json`, which will allow you to use ESM in your project's `node` scripts.
|
| 34 |
|
| 35 | ## Pages
|
| 36 |
|
| 37 | Microsite uses the file-system to generate your static site, meaning each component in `src/pages` outputs a corresponding HTML file.
|
| 38 |
|
| 39 | Page templates are `.js`, `.jsx`, or `.tsx` files which export a `default` a [Preact](https://preactjs.com/) component.
|
| 40 |
|
| 41 | ## Styles
|
| 42 |
|
| 43 | Styles are written using CSS Modules. `src/global.css` is, as you guessed, a global CSS file injected on every page.
|
| 44 | Per-page/per-component styles are also inject on the correct pages. They are modules and must be named `*.module.css`.
|
| 45 |
|
| 46 | ## Project structure
|
| 47 |
|
| 48 | ```
|
| 49 | project/
|
| 50 | ├── public/ // copied to dist/
|
| 51 | ├── src/
|
| 52 | │ ├── global/
|
| 53 | │ │ └── index.css // included in every generated page
|
| 54 | │ │ └── index.ts // shipped entirely to client, if present
|
| 55 | │ ├── pages/ // fs-based routing like Next.js
|
| 56 | │ │ └── index.tsx
|
| 57 | └── tsconfig.json
|
| 58 | ```
|
| 59 |
|
| 60 | ## Acknowledgments
|
| 61 |
|
| 62 | - [Markus Oberlehner](https://twitter.com/maoberlehner), [`vue-lazy-hydration`](https://github.com/maoberlehner/vue-lazy-hydration)
|
| 63 | - [Markus Oberlehner](https://twitter.com/maoberlehner), [Building Partially Hydrated, Progressively Enhanced Static Websites with Isomorphic Preact and Eleventy](https://markus.oberlehner.net/blog/building-partially-hydrated-progressively-enhanced-static-websites-with-isomorphic-preact-and-eleventy/)
|
| 64 | - [Lukas Bombach](https://twitter.com/luke_schmuke), [The case of partial hydration (with Next and Preact)](https://medium.com/@luke_schmuke/how-we-achieved-the-best-web-performance-with-partial-hydration-20fab9c808d5)
|
| 65 | - [Jason Miller](https://twitter.com/_developit) and [Addy Osmani](https://twitter.com/addyosmani), [Rendering on the Web](https://developers.google.com/web/updates/2019/02/rendering-on-the-web)
|
| 66 | - [Poimandres](https://github.com/pmndrs), [`valtio`](https://github.com/pmndrs/valtio) for inspiring `microsite/global`
|