Skip to content

Commit

Permalink
docs: improve readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@davidenke
davidenke committed Oct 24, 2024
1 parent 045be76 commit 324a88d
Showing 1 changed file with 65 additions and 18 deletions.
83 changes: 65 additions & 18 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,9 @@
<a href="https://github.com/davidenke/xmind-live-protocol/releases/latest"><img src="https://img.shields.io/github/v/release/davidenke/xmind-live-protocol
?label=latest" alt="Latest version"/></a>
<a href="https://github.com/davidenke/xmind-live-protocol/actions/workflows/release.yml"><img src="https://img.shields.io/github/actions/workflow/status/davidenke/xmind-live-protocol/release.yml?label=tests" alt="Test status"/></a>
<a href="https://github.com/davidenke/xmind-live-protocol"><img src="https://img.shields.io/badge/github-sources-blue" alt="Test and build status"/></a>
<a href="https://davidenke.github.io/xmind-live-protocol"><img src="https://img.shields.io/badge/demo-app-yellow?logoSize=50px" alt="Demo app"/></a>

# Xmind live protocol

This application converts a mind map into a protocol document.\
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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:

Expand All @@ -124,37 +136,51 @@ 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:

```bash
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):
Expand All @@ -168,10 +194,31 @@ 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/
[Vite]: https://vitejs.dev/
[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/

0 comments on commit 324a88d

Please sign in to comment.