diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index b4ad4181..9b4d5f5b 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -29,14 +29,23 @@ jobs: uses: actions/checkout@v3 with: fetch-depth: 0 # Not needed if lastUpdated is not enabled + - name: Setup Pages + uses: actions/configure-pages@v3 - name: Setup Node uses: actions/setup-node@v3 with: node-version: 18 cache: npm - - name: Setup Pages - uses: actions/configure-pages@v3 - - name: Install dependencies + - uses: ocaml/setup-ocaml@v2 + with: + ocaml-compiler: 5.1.1 + - name: Install all deps + run: make install + - name: Format check + run: make format-check + - name: Bundle the demo app + run: make bundle + - name: Install dependencies for VitePress run: | cd docs npm ci @@ -44,6 +53,8 @@ jobs: run: | cd docs npm run docs:build + - name: Move demo site into docs dir + run: mv dist docs/.vitepress/dist/demo - name: Deploy uses: peaceiris/actions-gh-pages@v3 with: diff --git a/Makefile b/Makefile index eb547e16..03d867ae 100644 --- a/Makefile +++ b/Makefile @@ -38,12 +38,13 @@ serve: ## Serve an application using a local HTTP server npx vite serve --open .PHONY: bundle -bundle: ## Bundle the JavaScript application +bundle: build ## Bundle the JavaScript application npx vite build .PHONY: clean clean: ## Clean build artifacts and other generated files $(DUNE) clean + rm -rf dist .PHONY: format format: ## Format the codebase with ocamlformat diff --git a/docs/.vitepress/config.js b/docs/.vitepress/config.js index d54da022..d02b670b 100644 --- a/docs/.vitepress/config.js +++ b/docs/.vitepress/config.js @@ -10,12 +10,13 @@ export default defineConfig({ title: "Melange for React Devs", description: "A project-based, guided introduction to Melange and its ecosystem for React developers", base: '/', + lastUpdated: true, themeConfig: { search: { provider: 'local' }, editLink: { - pattern: 'https://github.com/melange-re/melange-for-react-devs/edit/develop/docs/:path' + pattern: 'https://github.com/melange-re/melange-for-react-devs/edit/main/docs/:path' }, nav: [ { text: 'Home', link: '/' }, @@ -35,7 +36,7 @@ export default defineConfig({ { text: 'Introduction to Dune', link: '/intro-to-dune/' }, { text: 'Order Confirmation', link: '/order-confirmation/' }, { text: 'Styling with CSS', link: '/styling-with-css/' }, - { text: 'Better Sandwiches', link: '/better-sandwiches/'}, + { text: 'Better Sandwiches', link: '/better-sandwiches/' }, ] } ], diff --git a/docs/better-sandwiches/index.md b/docs/better-sandwiches/index.md index be6c9adb..09829d0b 100644 --- a/docs/better-sandwiches/index.md +++ b/docs/better-sandwiches/index.md @@ -145,6 +145,13 @@ except that they can only accept variables, not arbitrary expressions. Also note that unlike switch expressions, the `fun` syntax does not accept multi-line expressions in branches unless you add `{}` around them. +::: warning + +In Melange v2, `{j||j}` quoted string literals are not type-safe and so should +not be used in production code. This is fixed in Melange v3. + +::: + ## `Printf.sprintf` The OCaml standard library also provides a type-safe way to do string @@ -164,6 +171,13 @@ literals: logic for all primitive data types. This can often make your code shorter and easier to understand. +::: warning + +In Melange v2, the first argument of `Printf.sprintf` cannot contain unicode +characters. This is fixed in Melange v3. + +::: + ## Bundling An unfortunate downside of the `Printf` module is that using it can add a @@ -316,10 +330,11 @@ this](https://melange.re/v2.2.0/playground/?language=Reason&code=bGV0IGNvbXB1dGU ----- -[Source code for this -chapter](https://github.com/melange-re/melange-for-react-devs/blob/main/src/better-sandwiches/) -can be found in the [Melange for React Developers -repo](https://github.com/melange-re/melange-for-react-devs). +View [source +code](https://github.com/melange-re/melange-for-react-devs/blob/main/src/better-sandwiches/) +and [demo](https://react-book.melange.re/demo/src/better-sandwiches/) for this chapter. + +----- [^1]: Technically, undeclared variables produce a warning and it's possible to tell OCaml to not treat them as compilation errors. A common way to do this is diff --git a/docs/celsius-converter-exception/index.md b/docs/celsius-converter-exception/index.md index 5d49365b..f2090077 100644 --- a/docs/celsius-converter-exception/index.md +++ b/docs/celsius-converter-exception/index.md @@ -239,10 +239,11 @@ in the [ReasonReact](https://reasonml.github.io/reason-react/) docs. ----- -[Source code for this -chapter](https://github.com/melange-re/melange-for-react-devs/blob/main/src/celsius-converter-exception/) -can be found in the [Melange for React Developers -repo](https://github.com/melange-re/melange-for-react-devs). +View [source +code](https://github.com/melange-re/melange-for-react-devs/blob/main/src/celsius-converter-exception/) +and [demo](https://react-book.melange.re/demo/src/celsius-converter-exception/) for this chapter. + +----- [^1]: See [Using Js.t diff --git a/docs/celsius-converter-option/index.md b/docs/celsius-converter-option/index.md index 4f49a78c..4e087950 100644 --- a/docs/celsius-converter-option/index.md +++ b/docs/celsius-converter-option/index.md @@ -195,7 +195,6 @@ expression: ----- -[Source code for this -chapter](https://github.com/melange-re/melange-for-react-devs/blob/main/src/celsius-converter-option/) -can be found in the [Melange for React Developers -repo](https://github.com/melange-re/melange-for-react-devs). +View [source +code](https://github.com/melange-re/melange-for-react-devs/blob/main/src/celsius-converter-option/) +and [demo](https://react-book.melange.re/demo/src/celsius-converter-option/) for this chapter. diff --git a/docs/counter/index.md b/docs/counter/index.md index 1de88bf5..30bc4717 100644 --- a/docs/counter/index.md +++ b/docs/counter/index.md @@ -194,10 +194,11 @@ is a very common newbie mistake. See the [PPX chapter](/todo) for more details. ----- -[Source code for this -chapter](https://github.com/melange-re/melange-for-react-devs/blob/main/src/counter/) -can be found in the [Melange for React Developers -repo](https://github.com/melange-re/melange-for-react-devs). +View [source +code](https://github.com/melange-re/melange-for-react-devs/blob/main/src/counter/) +and [demo](https://react-book.melange.re/demo/src/counter/) for this chapter. + +----- [^1]: Despite the name, don't confuse OCaml's *switch expressions* with JavaScript's *switch statements*. diff --git a/docs/intro-to-dune/index.md b/docs/intro-to-dune/index.md index 0d68b85d..254702db 100644 --- a/docs/intro-to-dune/index.md +++ b/docs/intro-to-dune/index.md @@ -359,14 +359,16 @@ character instead of space characters. ----- -Source code for this chapter can be found in the [Melange for React Developers -repo](https://github.com/melange-re/melange-for-react-devs): +Source code for this chapter: +- [`src` folder containing all projects](https://github.com/melange-re/melange-for-react-devs/tree/main/src) - [Counter project](https://github.com/melange-re/melange-for-react-devs/tree/main/src/counter) - [Celsius Converter project](https://github.com/melange-re/melange-for-react-devs/tree/main/src/celsius-converter-option) +----- + [^1]: The full list of files we'd need to create for every project would actually be `dune-project`, `.opam`, `package.json`, `index.html`, and `vite.config.js`. diff --git a/docs/intro/index.md b/docs/intro/index.md index 039cae56..1803a2b2 100644 --- a/docs/intro/index.md +++ b/docs/intro/index.md @@ -1,7 +1,17 @@ # Melange for React Developers ::: warning + This is a work in progress. + +::: + +::: info + +The content here targets [Melange +v3](https://docs.google.com/document/d/1q9NWiXun_Lqgv5iNNYm2SKzUGGJ02FpRawKUiTxnJPI/edit#heading=h.9je9ws3oydaz), +so if you are using Melange v2, a few things might not work quite the same. + ::: ## Motivation diff --git a/docs/numeric-types/index.md b/docs/numeric-types/index.md index 708c9dcf..9c66f4df 100644 --- a/docs/numeric-types/index.md +++ b/docs/numeric-types/index.md @@ -268,7 +268,6 @@ Js.log(result); // prints [0,58] ----- -[Source code for this -chapter](https://github.com/melange-re/melange-for-react-devs/blob/main/src/numeric-types/) -can be found in the [Melange for React Developers -repo](https://github.com/melange-re/melange-for-react-devs). +View [source +code](https://github.com/melange-re/melange-for-react-devs/blob/main/src/numeric-types/) +and [demo](https://react-book.melange.re/demo/src/numeric-types/) for this chapter. diff --git a/docs/order-confirmation/index.md b/docs/order-confirmation/index.md index 0e539e36..ce590a3f 100644 --- a/docs/order-confirmation/index.md +++ b/docs/order-confirmation/index.md @@ -358,10 +358,11 @@ Then we can use that function like this: ----- -[Source code for this -chapter](https://github.com/melange-re/melange-for-react-devs/blob/main/src/order-confirmation/) -can be found in the [Melange for React Developers -repo](https://github.com/melange-re/melange-for-react-devs). +View [source +code](https://github.com/melange-re/melange-for-react-devs/blob/main/src/order-confirmation/) +and [demo](https://react-book.melange.re/demo/src/order-confirmation/) for this chapter. + +----- [^1]: Variant types have no equivalent in JavaScript, but they are similar to TypeScript's [union diff --git a/docs/styling-with-css/index.md b/docs/styling-with-css/index.md index 2c3e6e4c..9b626eb4 100644 --- a/docs/styling-with-css/index.md +++ b/docs/styling-with-css/index.md @@ -286,10 +286,11 @@ decent amount of code out in the wild that uses `bs.module`. ----- -[Source code for this -chapter](https://github.com/melange-re/melange-for-react-devs/blob/main/src/styling-with-css/) -can be found in the [Melange for React Developers -repo](https://github.com/melange-re/melange-for-react-devs). +View [source +code](https://github.com/melange-re/melange-for-react-devs/blob/main/src/styling-with-css/) +and [demo](https://react-book.melange.re/demo/src/styling-with-css/) for this chapter. + +----- [^1]: The `css-loader` plugin allows you to import CSS files and the `style-loader` plugin injects imported CSS into the DOM. diff --git a/index.html b/index.html index b6a28b7e..b788ec21 100644 --- a/index.html +++ b/index.html @@ -1,7 +1,8 @@ - + + Melange for React Developers diff --git a/src/better-sandwiches/index.html b/src/better-sandwiches/index.html index 42cb8131..760bb0ef 100644 --- a/src/better-sandwiches/index.html +++ b/src/better-sandwiches/index.html @@ -1,7 +1,8 @@ - + + Melange for React Devs diff --git a/src/celsius-converter-exception/index.html b/src/celsius-converter-exception/index.html index fb529ce8..476278f9 100644 --- a/src/celsius-converter-exception/index.html +++ b/src/celsius-converter-exception/index.html @@ -1,7 +1,8 @@ - + + Melange for React Devs diff --git a/src/celsius-converter-option/index.html b/src/celsius-converter-option/index.html index 2a1efc74..0b13b356 100644 --- a/src/celsius-converter-option/index.html +++ b/src/celsius-converter-option/index.html @@ -1,7 +1,8 @@ - + + Melange for React Devs diff --git a/src/counter/index.html b/src/counter/index.html index f2aa2ad2..aaee7b70 100644 --- a/src/counter/index.html +++ b/src/counter/index.html @@ -1,7 +1,8 @@ - + + Melange for React Devs diff --git a/src/numeric-types/index.html b/src/numeric-types/index.html index 3c0a0e2f..da606e31 100644 --- a/src/numeric-types/index.html +++ b/src/numeric-types/index.html @@ -1,7 +1,8 @@ - + + Melange for React Devs diff --git a/src/order-confirmation/index.html b/src/order-confirmation/index.html index 1acaea7e..3256a0b7 100644 --- a/src/order-confirmation/index.html +++ b/src/order-confirmation/index.html @@ -1,7 +1,8 @@ - + + Melange for React Devs diff --git a/src/styling-with-css/index.html b/src/styling-with-css/index.html index d6156b52..4d1cc37f 100644 --- a/src/styling-with-css/index.html +++ b/src/styling-with-css/index.html @@ -1,7 +1,8 @@ - + + Melange for React Devs diff --git a/vite.config.js b/vite.config.js index d1857b21..48057f3f 100644 --- a/vite.config.js +++ b/vite.config.js @@ -3,6 +3,7 @@ import { defineConfig } from 'vite' import { nodeResolve } from '@rollup/plugin-node-resolve' export default defineConfig({ + base: '/demo/', // nodeResolve is needed to import melange runtime libraries in output // directory's `node_modules` directory. See // https://github.com/melange-re/melange-for-react-devs/pull/16#discussion_r1455989106 @@ -12,4 +13,18 @@ export default defineConfig({ ignored: ['**/_opam'] } }, + build: { + rollupOptions: { + input: { + 'main': resolve(__dirname, 'index.html'), + 'counter': resolve(__dirname, 'src/counter/index.html'), + 'numeric-types': resolve(__dirname, 'src/numeric-types/index.html'), + 'celsius-converter-exception': resolve(__dirname, 'src/celsius-converter-exception/index.html'), + 'celsius-converter-option': resolve(__dirname, 'src/celsius-converter-option/index.html'), + 'order-confirmation': resolve(__dirname, 'src/order-confirmation/index.html'), + 'styling-with-css': resolve(__dirname, 'src/styling-with-css/index.html'), + 'better-sandwiches': resolve(__dirname, 'src/better-sandwiches/index.html'), + }, + }, + }, });