diff --git a/.vscode/settings.json b/.vscode/settings.json index 51751f5c68..36ef3a3bf3 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -43,6 +43,18 @@ "[terraform]": { "editor.defaultFormatter": "hashicorp.terraform" }, + "[markdown]": { + "editor.unicodeHighlight.ambiguousCharacters": false, + "editor.unicodeHighlight.invisibleCharacters": false, + "diffEditor.ignoreTrimWhitespace": false, + "editor.wordWrap": "on", + "editor.wordWrapColumn": 80, + "editor.quickSuggestions": { + "comments": "off", + "strings": "off", + "other": "off" + } + }, "[shellscript]": { "editor.detectIndentation": false, "editor.insertSpaces": false, diff --git a/dev b/dev index a608f02f6d..6be9fe6c66 100755 --- a/dev +++ b/dev @@ -111,11 +111,18 @@ def main(): ) @cmd( - cmds, "validate", "Formats, Validates and test the site app" + cmds, "frontend-validate", "Formats, Validates" ) def validate(args): run("yarn validate") + + @cmd( + cmds, "frontend-test", "Tests frontend code" + ) + def validate(args): + run("yarn test") + @cmd(cmds, "run-backend", "Build and run mintterd binary for the current platform.") def run_backend(args): return run("plz run //backend:mintterd", args=args) diff --git a/docs/docs/assets/Mintter_IPFS_Camp_2022 1.gif b/docs/docs/assets/Mintter_IPFS_Camp_2022 1.gif deleted file mode 100644 index 083a917957..0000000000 Binary files a/docs/docs/assets/Mintter_IPFS_Camp_2022 1.gif and /dev/null differ diff --git a/docs/docs/assets/Mintter_IPFS_Camp_2022.gif b/docs/docs/assets/Mintter_IPFS_Camp_2022.gif deleted file mode 100644 index 0d4b0dd7a1..0000000000 Binary files a/docs/docs/assets/Mintter_IPFS_Camp_2022.gif and /dev/null differ diff --git a/docs/docs/assets/Screenshot_2023-01-03_at_16.39.42.png b/docs/docs/assets/Screenshot_2023-01-03_at_16.39.42.png deleted file mode 100644 index ccbde50a74..0000000000 Binary files a/docs/docs/assets/Screenshot_2023-01-03_at_16.39.42.png and /dev/null differ diff --git a/docs/docs/assets/dev-setup-local-run.png b/docs/docs/assets/dev-setup-local-run.png deleted file mode 100644 index 9ae4ae21e1..0000000000 Binary files a/docs/docs/assets/dev-setup-local-run.png and /dev/null differ diff --git a/docs/docs/assets/dev-setup-root-terminal.png b/docs/docs/assets/dev-setup-root-terminal.png deleted file mode 100644 index 8ccbd58cbb..0000000000 Binary files a/docs/docs/assets/dev-setup-root-terminal.png and /dev/null differ diff --git a/docs/docs/assets/diagram-app-architecture.png b/docs/docs/assets/diagram-app-architecture.png deleted file mode 100644 index 1d32fd9ae0..0000000000 Binary files a/docs/docs/assets/diagram-app-architecture.png and /dev/null differ diff --git a/docs/docs/assets/diagram-ipfs-pointer.png b/docs/docs/assets/diagram-ipfs-pointer.png deleted file mode 100644 index fc3f32dd07..0000000000 Binary files a/docs/docs/assets/diagram-ipfs-pointer.png and /dev/null differ diff --git a/docs/docs/assets/diagram-triplestore-table.png b/docs/docs/assets/diagram-triplestore-table.png deleted file mode 100644 index 8e30563d7a..0000000000 Binary files a/docs/docs/assets/diagram-triplestore-table.png and /dev/null differ diff --git a/docs/docs/assets/encryption-callout.png b/docs/docs/assets/encryption-callout.png deleted file mode 100644 index ac0bb3f94f..0000000000 Binary files a/docs/docs/assets/encryption-callout.png and /dev/null differ diff --git a/docs/docs/assets/frontend-app-draft-item-menu.png b/docs/docs/assets/frontend-app-draft-item-menu.png deleted file mode 100644 index 5f97e2571c..0000000000 Binary files a/docs/docs/assets/frontend-app-draft-item-menu.png and /dev/null differ diff --git a/docs/docs/assets/frontend-app-menu.png b/docs/docs/assets/frontend-app-menu.png deleted file mode 100644 index c676339793..0000000000 Binary files a/docs/docs/assets/frontend-app-menu.png and /dev/null differ diff --git a/docs/docs/assets/frontend-app-publication-item-menu.png b/docs/docs/assets/frontend-app-publication-item-menu.png deleted file mode 100644 index 6072efed2f..0000000000 Binary files a/docs/docs/assets/frontend-app-publication-item-menu.png and /dev/null differ diff --git a/docs/docs/assets/ui-inbox.png b/docs/docs/assets/ui-inbox.png deleted file mode 100644 index 3538730762..0000000000 Binary files a/docs/docs/assets/ui-inbox.png and /dev/null differ diff --git a/docs/docs/assets/ui-publication-and-activity.png b/docs/docs/assets/ui-publication-and-activity.png deleted file mode 100644 index dc87fd84bd..0000000000 Binary files a/docs/docs/assets/ui-publication-and-activity.png and /dev/null differ diff --git a/docs/docs/assets/ui-publication.png b/docs/docs/assets/ui-publication.png deleted file mode 100644 index ac8d5ecb1d..0000000000 Binary files a/docs/docs/assets/ui-publication.png and /dev/null differ diff --git a/docs/docs/assets/ui-transclusions.png b/docs/docs/assets/ui-transclusions.png deleted file mode 100644 index 8b39cd7919..0000000000 Binary files a/docs/docs/assets/ui-transclusions.png and /dev/null differ diff --git a/docs/docs/assets/what-is-mintter-1.png b/docs/docs/assets/what-is-mintter-1.png deleted file mode 100644 index ba14e38432..0000000000 Binary files a/docs/docs/assets/what-is-mintter-1.png and /dev/null differ diff --git a/docs/docs/assets/what-is-mintter-10.png b/docs/docs/assets/what-is-mintter-10.png deleted file mode 100644 index 1729cc66fd..0000000000 Binary files a/docs/docs/assets/what-is-mintter-10.png and /dev/null differ diff --git a/docs/docs/assets/what-is-mintter-11.png b/docs/docs/assets/what-is-mintter-11.png deleted file mode 100644 index a5e46bfda1..0000000000 Binary files a/docs/docs/assets/what-is-mintter-11.png and /dev/null differ diff --git a/docs/docs/assets/what-is-mintter-12.png b/docs/docs/assets/what-is-mintter-12.png deleted file mode 100644 index 303b7445cc..0000000000 Binary files a/docs/docs/assets/what-is-mintter-12.png and /dev/null differ diff --git a/docs/docs/assets/what-is-mintter-13.png b/docs/docs/assets/what-is-mintter-13.png deleted file mode 100644 index af755e11a8..0000000000 Binary files a/docs/docs/assets/what-is-mintter-13.png and /dev/null differ diff --git a/docs/docs/assets/what-is-mintter-14.png b/docs/docs/assets/what-is-mintter-14.png deleted file mode 100644 index 7611670aae..0000000000 Binary files a/docs/docs/assets/what-is-mintter-14.png and /dev/null differ diff --git a/docs/docs/assets/what-is-mintter-15.png b/docs/docs/assets/what-is-mintter-15.png deleted file mode 100644 index 404a38c1dd..0000000000 Binary files a/docs/docs/assets/what-is-mintter-15.png and /dev/null differ diff --git a/docs/docs/assets/what-is-mintter-16.png b/docs/docs/assets/what-is-mintter-16.png deleted file mode 100644 index 6c25c54bed..0000000000 Binary files a/docs/docs/assets/what-is-mintter-16.png and /dev/null differ diff --git a/docs/docs/assets/what-is-mintter-17.png b/docs/docs/assets/what-is-mintter-17.png deleted file mode 100644 index f003b6ef75..0000000000 Binary files a/docs/docs/assets/what-is-mintter-17.png and /dev/null differ diff --git a/docs/docs/assets/what-is-mintter-18.png b/docs/docs/assets/what-is-mintter-18.png deleted file mode 100644 index 6e3de4974d..0000000000 Binary files a/docs/docs/assets/what-is-mintter-18.png and /dev/null differ diff --git a/docs/docs/assets/what-is-mintter-19.png b/docs/docs/assets/what-is-mintter-19.png deleted file mode 100644 index 55f3e28bb6..0000000000 Binary files a/docs/docs/assets/what-is-mintter-19.png and /dev/null differ diff --git a/docs/docs/assets/what-is-mintter-2.png b/docs/docs/assets/what-is-mintter-2.png deleted file mode 100644 index 5d8553e1e6..0000000000 Binary files a/docs/docs/assets/what-is-mintter-2.png and /dev/null differ diff --git a/docs/docs/assets/what-is-mintter-20.png b/docs/docs/assets/what-is-mintter-20.png deleted file mode 100644 index 89bddfc6e7..0000000000 Binary files a/docs/docs/assets/what-is-mintter-20.png and /dev/null differ diff --git a/docs/docs/assets/what-is-mintter-3.png b/docs/docs/assets/what-is-mintter-3.png deleted file mode 100644 index f8cb0aed25..0000000000 Binary files a/docs/docs/assets/what-is-mintter-3.png and /dev/null differ diff --git a/docs/docs/assets/what-is-mintter-4.png b/docs/docs/assets/what-is-mintter-4.png deleted file mode 100644 index 23b436f51d..0000000000 Binary files a/docs/docs/assets/what-is-mintter-4.png and /dev/null differ diff --git a/docs/docs/assets/what-is-mintter-5.png b/docs/docs/assets/what-is-mintter-5.png deleted file mode 100644 index 67d05ecee1..0000000000 Binary files a/docs/docs/assets/what-is-mintter-5.png and /dev/null differ diff --git a/docs/docs/assets/what-is-mintter-6.png b/docs/docs/assets/what-is-mintter-6.png deleted file mode 100644 index e86e4c483f..0000000000 Binary files a/docs/docs/assets/what-is-mintter-6.png and /dev/null differ diff --git a/docs/docs/assets/what-is-mintter-7.png b/docs/docs/assets/what-is-mintter-7.png deleted file mode 100644 index 694115cc9d..0000000000 Binary files a/docs/docs/assets/what-is-mintter-7.png and /dev/null differ diff --git a/docs/docs/assets/what-is-mintter-8.png b/docs/docs/assets/what-is-mintter-8.png deleted file mode 100644 index 8958c2b7dc..0000000000 Binary files a/docs/docs/assets/what-is-mintter-8.png and /dev/null differ diff --git a/docs/docs/assets/what-is-mintter-9.png b/docs/docs/assets/what-is-mintter-9.png deleted file mode 100644 index 909580d39b..0000000000 Binary files a/docs/docs/assets/what-is-mintter-9.png and /dev/null differ diff --git a/docs/docs/assets/what-is-mintter.png b/docs/docs/assets/what-is-mintter.png deleted file mode 100644 index 9652c0d66c..0000000000 Binary files a/docs/docs/assets/what-is-mintter.png and /dev/null differ diff --git a/docs/docs/frontend-dev-setup.md b/docs/docs/frontend-dev-setup.md index c8f1cd36e3..cb0c2a190e 100644 --- a/docs/docs/frontend-dev-setup.md +++ b/docs/docs/frontend-dev-setup.md @@ -1,11 +1,63 @@ # Frontend Development Setup +- [Frontend Development Setup](#frontend-development-setup) + - [TLDR;](#tldr) + - [Introduction](#introduction) + - [Prerequisites](#prerequisites) + - [./dev scripts](#dev-scripts) + - [Desktop app](#desktop-app) + - [Run the desktop app locally](#run-the-desktop-app-locally) + - [Build the desktop app locally](#build-the-desktop-app-locally) + - [Sites](#sites) + - [Run the Site app locally](#run-the-site-app-locally) + - [Build sites locally](#build-sites-locally) + - [Scoped package](#scoped-package) + - [Monorepo Architecrure](#monorepo-architecrure) + - [Inspirations and Special mentions](#inspirations-and-special-mentions) + +## TLDR; + +⚠️ make sure you [setup the project tools](./dev-setup) ⚠️ -The Mintter Frontend architecture is based on a [yarn](https://yarnpkg.com) workspace. Currently we have this packages: +```bash +git clone + +cd mintter +yarn install + +# desktop app: for local development +./dev run-desktop + +# desktop app: to build locally +./dev build-desktop + +# site: for local development: TBD +# site: for local build: TBD + +# validate frontend code +./dev frontend-validate + +# test frontend code +./dev frontend-test +``` + +## Introduction + +The Mintter Frontend architecture is based on a [yarn](https://yarnpkg.com) workspace. All the frontend code can be found inside the [`./frontend`](../../frontend) folder. The app is using a monorepo structure inspired by the [Create Tamagui App template](https://tamagui.dev/docs/guides/create-tamagui-app). + +- all the apps packages are inside the [`apps`](../../frontend/apps) folder. +- all the scoped packages that are reused inside each app are in the [`packages`](../../frontend/packages) folder. +- we are not required to build individual packages before building the apps. The apps are the ones in charge of building all the necesary codebase and pull the packages code from source (using [tsconfig paths](https://www.typescriptlang.org/tsconfig#paths)) We explained this in more detail in [#monorepo-architecture] + +Now let's describe each package and what it does + +1. [`apps/desktop`](../../frontend/packages/app): The Local-first Desktop app built with [Electron](https://electronjs.com) +1. [`apps/site`](../../frontend/packages/app): The Self-hosted sites anyone can run on their own servers built using [NextJS](https://nextjs.org) +1. [`packages/app`](../../frontend/packages/app): All the "screens" for the local-first apps (currently only `desktop`, soon others...) +1. [`packages/ui`](../../frontend/packages/ui): All the individual UI components and the theme setup for all the apps. +1. [`packages/shared`](../../frontend/packages/shared): All the code that interface with the local backend API and gRPC. +1. [`packages/eslint-config-custom`](../../frontend/packages/eslint-config-custom): the base eslint config for all the frontend code +1. [`packages/prettier-config`](../../frontend/packages/prettier-config): the base formatting config for all the frontend code. -1. App Package: for the desktop app code lives -2. Gateway: for the gateway code -3. Shared: for the shared API-related code -4. UI (soon): for all the design system/common UI building blocks for all the Mintter applications After you [setup the project](./dev-setup) on your local machine, you should have `yarn` available, so no need to install it globally. @@ -13,11 +65,30 @@ After you [setup the project](./dev-setup) on your local machine, you should hav Please make sure that after you enter the repo root path, you see something similar to this showing the necessary Environment variables set: -![dev-setup-root-terminal.png](./assets/dev-setup-root-terminal.png) +[![dev setup showcase](https://img.youtube.com/vi/l5smHCf1AYA/0.jpg)](https://www.youtube.com/watch?v=l5smHCf1AYA) + +After this is correct, you should run `yarn install` (or `yarn`) to start the dev setup. [Nix](./nix.md) is helping us installing all the necessary tools and setup we need to run every script and app inside the repo. Don't worry of having the exact version of yarn or any other tool, Nix got us covered! + +## ./dev scripts -After this is correct, you should run `yarn install` (or `yarn`) to install all the frontend packages. +Because Mintter uses multiple tools with multiple languages, we set a file with all the local scripts you can run to setup, build, validate and test the project. -## Run the Desktop app locally +## Desktop app + +The desktop app is the main Application that users can have to interact and collaborate inside the Hyperdocs Protocol. Everything works locally and there's no need to servers or Internet connection. + +This application is built with this main tools and frameworks: + +- Electron (with electron-forge) +- Vite +- Tamagui +- React +- BlockNote (build with TipTap and Prosemirror) +- Radix UI +- Unified +- TRPC + +### Run the desktop app locally because we are using [Nix](./nix), we are able to create custom orchestrated commands in order to setup everything properly for any situation. To run the desktop app locally, you just need to run: @@ -27,42 +98,72 @@ because we are using [Nix](./nix), we are able to create custom orchestrated com This command should trigger a set of processes that eventually should launch the app in dev mode -![Locally running the Desktop app](./assets/dev-setup-local-run.png) +[![Running the desktop app locally](https://img.youtube.com/vi/EQDLgjfgp90/0.jpg)](https://www.youtube.com/watch?v=EQDLgjfgp90) -> you can also run `./dev` to print the stript's readme and see all the possible commands/options. You can checkout all the commands [here](https://github.com/mintterteam/mintter/blob/master/dev) +Keep in mind that `./dev run-desktop` runs both the desktop app **and the go backend**. This is setup this way for convenience and ease of use. -Keep in mind that `./dev run-desktop` runs both the desktop app **and the go backend**. This is setup this way for convenience and ease of use. You are able to run _just_ the desktop frontend code by running: +### Build the desktop app locally + +To build the desktop app locally you can simply run the next command: ```bash -./dev run-frontend +./dev build-desktop ``` -> You can also run _just_ the backend with `./dev run-backend` +This will build the Application based on the platform you are currently running. We support MacOS, Linux and Windows. -## Run the Gateway app locally +If you have any issues running the application or building the application locally, please [file an issue](https://github.com/mintterteam/mintter/issues/new/choose) with the platform you are running on and we will address it as fast as we can. -The same way we can run the desktop app with a `./dev` command, you have access to gateway-specific commands: +## Sites -```bash -./dev run-gw-frontend # run the gateway frontend _only_ (dev mode) -./dev run-gw-bacend # run the gateway backend _only_ (dev mode) -``` +TBD +### Run the Site app locally + +TBD (we need to finish the groups setup to see how will be) +### Build sites locally -## Shared package +TBD (we need to finish the groups setup to see how will be) -The frontend shared package is wrapping all the API/Backend related code that is shared between both the desktop app and the web gateway. You don't have to manually run any command for this, but you can check the specific commands defined for this package in the [root `package.json`](../package.json). +## Scoped package -## Per-package scripts overview +All the packages inside the [`packages` folder](../../frontend/packages) are used as source code inside both apps. There's no need to build them separately. + +This is possible in our case because we are not intended to publish this packages separate from the app. For us, there's no need to setup all the madness needed in order for publish individual packages and develop with then locally in a sensible way. Mayb ein the future, who knows! + +## Monorepo Architecrure + +Like I mentioned before, this monorepo does not follow some conventions other monorepos might do. This are the essential requirements we need at the moment that this setup fulfills: + +- we want to separate the code into its own scope +- we use Typescript +- we don't need to build individual packages, only the apps +- we want to import files using the package name, but import from the source (the actual package) + +To achieve this, based on the code structure we adopted thanks to [Tamagui](https://tamagui.dev), we are mainly using [TSConfig paths](https://www.typescriptlang.org/tsconfig#paths) to make sure typescript understands from where it needs to pull the package's code. + +```json +// ./frontend/apps/desktop/tsconfig.json +{ + "compilerOptions": { + // ... + "baseUrl": ".", + "paths": { + "*": ["*"], + "@mintter/ui": ["*", "../../packages/ui/src/index.tsx"], + "@mintter/shared": ["*", "../../packages/shared/src/index.ts"], + "@mintter/app/*": ["*", "../../packages/app/src/*"], + "react-native": ["react-native-web"] + } + }, + // ... +} +``` -For every frontend package, there's a set of required scripts in order to keep consistency inside all the project: +Another change that we did is that in each scoped package's `package.json` file, we are not setting anything related to exports nor types. WE found that doing this makes it simple for `tsc` compiler to find the correct files based on the paths set. -1. `dev`: run the current package in dev mode. -2. `build`: build the current package. -3. `test`: run all the possible tests inside the current package. -4. `lint`: run all the possible linters inside the current package. -5. `format`: format the code for the current package. -6. `validate`: lint + test the current package. +You can also see that on each scoped package there's only 2 or 3 scripts set: `lint`, `format` and `test`. While we don't want to build this packages individually, we do want to make sure the code structure and linting follows the project's rules. -> if you are creating a new frontend package, please make sure you create this scripts properly and connect them with the appropiate `./dev` script. +### Inspirations and Special mentions +We took a lot of inspirations from tools like [Tamagui](https://tamagui.dev), [Turbo](https://turbo.build/repo) and tutorials like [Monorepo Maestros](https://www.shew.dev/monorepos).