diff --git a/README.md b/README.md index 2159d74..ab4a950 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,9 @@ +Latest version +Test status +Test and build status +Demo app + # Xmind live protocol This application converts a mind map into a protocol document.\ @@ -60,10 +66,16 @@ Assuming you have [Rust], [nvm][nvm-nix] and [pnpm] installed, you can run the a ```bash # install dependencies nvm use && pnpm i -# start app locally with dev servers + +# start app with dev servers pnpm dev -# start frontend detached + +# start frontend only pnpm dev:detached + +# build and preview demo +./node_modules/.bin/vite build --mode detached && \ +./node_modules/.bin/vite preview --mode detached ``` ### Prerequisites @@ -114,7 +126,7 @@ nvm use $(cat .nvmrc) pnpm install ``` -#### Run development server +### Run development server To conveniently develop the application, you can start the development server with the following command: @@ -124,7 +136,11 @@ pnpm dev This will start the frontend using [Vite] and the backend using [Tauri]. -#### Build application +> To start the frontend detached, you can use `pnpm dev:detached`. This will mock the Tauri APIs and allow you to develop the frontend in a browser.\ +> This is achieved by running `vite` with the `detached` mode:\ +> `./node_modules/.bin/vite dev --mode detached`. + +### Build application To build the application for distribution, you can run the following command: @@ -132,29 +148,39 @@ To build the application for distribution, you can run the following command: pnpm build ``` -## Node backend +> At least on the CI a build for a demo browser only version is created, which is deployed to GitHub Pages. This is also done by building with the `detached` mode:\ +> `./node_modules/.bin/vite build --mode detached`. -Conversion of markdown to docx in the browser comes to a cost. We use [@adobe/helix-md2docx](https://www.npmjs.com/package/@adobe/helix-md2docx), which unfortunately uses dependencies importing node modules.\ -Thus, we have to mock those modules in our build tooling for usage in a browser context. +> As [Vite] does fast development builds with [esbuild], it uses [rollup] for production. This results in different build outputs, so the application may behaves differently.\ +> To test the demo build locally, you can preview the `detached` result **after building it**:\ +> `./node_modules/.bin/vite preview --mode detached` -As alternative approach, I considered conversion on the backend using a [Node.js] service.\ -This could be loaded in [Tauri via Sidecar](https://tauri.app/learn/sidecar-nodejs/). To do so, the Node service must be packed into a single binary file, which can be loaded by the Tauri application. +## Deployment -In the Tauri examples [pkg](https://github.com/vercel/pkg) is used to pack the Node service.\ -However, this module is not maintained anymore. But fortunately, this has become a first class citizen in Node.js called [Single Executable Application (SEA)](https://nodejs.org/docs/latest-v20.x/api/single-executable-applications.html#single-executable-application-creation-process). Based on this documentation, I roughly automated this steps with a little [CLI tool](./scripts/prepare-sidecar.ts).\ -It can be used calling: +A browser only,preview of the application is [deployed to GitHub Pages](https://davidenke.github.io/xmind-live-protocol) on every release [by a GitHub Action](./.github/workflows/release.yml). -```bash -npx -y tsx ./scripts/prepare-sidecar.ts --from ./src-node/index.ts -``` +This happens every time when changes are pushed to the `main` branch. -It still needs to be tested on the CI, as it is unsure if the [requirements](https://github.com/nodejs/postject?tab=readme-ov-file#prerequisites) are fulfilled there. Maybe there already is a GitHub Action for this. +## Release + +Releases are created by CI only [by a GitHub Action](./.github/workflows/release.yml). This happens in the following steps: + +1. Checkout with complete history +1. Install all dependencies (including [Rust], [Node.js], and [pnpm]) +1. Prepare a new release with [release-it] +1. Build the application + 1. In a matrix job for all platforms, add the artifacts to the release + 1. A demo build for the browser only, to be deployed to GitHub Pages + +This happens every time when changes are pushed to the `main` branch. -## Icons +## Miscellaneous + +### Icons Most of the app icons are generated after installation using [the `tauri icon` command](https://v1.tauri.app/v1/guides/features/icons/) (s. `prepare` script in [`package.json`](./package.json)). -### App icon +#### App icon The only exception is the macOS icon, which is configured to be used from the [`./src/assets/icons/app.icon.icns` path](./src/assets/icons/app.icon.icns) directly. \ This icon is sourced from its Adobe Illustrator file [`./src/assets/icons/app.icns.ai`](./src/assets/icons/app.icns.ai): @@ -168,6 +194,24 @@ This icon is sourced from its Adobe Illustrator file [`./src/assets/icons/app.ic > As this should not happen very often, this process is not automated but documented here, just as a brief reminder. +### Node backend + +Conversion of markdown to docx in the browser comes to a cost. We use [@adobe/helix-md2docx](https://www.npmjs.com/package/@adobe/helix-md2docx), which unfortunately uses dependencies importing node modules.\ +Thus, we have to mock those modules in our build tooling for usage in a browser context. + +As alternative approach, I considered conversion on the backend using a [Node.js] service.\ +This could be loaded in [Tauri via Sidecar](https://tauri.app/learn/sidecar-nodejs/). To do so, the Node service must be packed into a single binary file, which can be loaded by the Tauri application. + +In the Tauri examples [pkg](https://github.com/vercel/pkg) is used to pack the Node service.\ +However, this module is not maintained anymore. But fortunately, this has become a first class citizen in Node.js called [Single Executable Application (SEA)](https://nodejs.org/docs/latest-v20.x/api/single-executable-applications.html#single-executable-application-creation-process). Based on this documentation, I roughly automated this steps with a little [CLI tool](./scripts/prepare-sidecar.ts).\ +It can be used calling: + +```bash +npx -y tsx ./scripts/prepare-sidecar.ts --from ./src-node/index.ts +``` + +It still needs to be tested on the CI, as it is unsure if the [requirements](https://github.com/nodejs/postject?tab=readme-ov-file#prerequisites) are fulfilled there. Maybe there already is a GitHub Action for this. + [Rust]: https://www.rust-lang.org/ [pnpm]: https://pnpm.io/ [Tauri]: https://tauri.app/ @@ -175,3 +219,6 @@ This icon is sourced from its Adobe Illustrator file [`./src/assets/icons/app.ic [Node.js]: https://nodejs.org/ [nvm-nix]: https://github.com/nvm-sh/nvm [nvm-win]: https://github.com/coreybutler/nvm-windows +[release-it]: github.com/release-it/release-it +[esbuild]: https://esbuild.github.io/ +[rollup]: https://rollupjs.org/