From 6b35f167389b6cb5a18215f9d33e4fd7d2e5f055 Mon Sep 17 00:00:00 2001 From: Tilman Vatteroth Date: Sun, 2 Oct 2022 21:59:42 +0200 Subject: [PATCH] fix(docs): Restructure README.md Signed-off-by: Tilman Vatteroth --- README.md | 92 +++++++++++++++++++++---------------- dev-reverse-proxy/README.md | 12 ----- package.json | 2 +- 3 files changed, 53 insertions(+), 53 deletions(-) delete mode 100644 dev-reverse-proxy/README.md diff --git a/README.md b/README.md index ce842586f..8e3060dab 100644 --- a/README.md +++ b/README.md @@ -12,71 +12,83 @@ SPDX-License-Identifier: CC-BY-SA-4.0 [![Language grade: JavaScript](https://img.shields.io/lgtm/grade/javascript/g/hedgedoc/react-client.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/hedgedoc/react-client/context:javascript) [![Total alerts](https://img.shields.io/lgtm/alerts/g/hedgedoc/react-client.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/hedgedoc/react-client/alerts/) -This is the new, improved and better looking frontend for HedgeDoc 2.0. Our goal is to recreate the current frontend in -react and to improve it. +This is the new, improved and better looking frontend for HedgeDoc 2.0. +Our goal is to recreate the current frontend in react and to improve it. + +## UI Test + +Curious about the new look and feel? We provide a demo of the new UI on [hedgedoc.dev](https://hedgedoc.dev). This +version uses mocked data and has no data persistence. + +The UI test is hosted by [netlify](https://netlify.com). Please check +their [privacy policy](https://netlify.com/privacy) as well as [ours](https://hedgedoc.org/privacy-policy). ## Preparation You need at least Node 14 (we recommend Node 18) and [yarn](https://yarnpkg.com/). You MUST use yarn! There is no support for npm. -## Development mode - 1. Clone this repo (e.g. `git clone https://github.com/hedgedoc/react-client.git hedgedoc-react-client`) 2. Go inside the repo (e.g. `cd hedgedoc-react-client`) 3. Run `yarn install` -4. Either run - - `yarn dev` - Calls only mocked version of the api. Doesn't need a HedgeDoc backend. - - `yarn start:for-real-backend` - - Expects [a HedgeDoc backend server](https://github.com/hedgedoc/hedgedoc/tree/develop) running - under [http://localhost:3000](http://localhost:3000)) -This should run the app in the development mode and open [http://localhost:3001](http://localhost:3001) in your browser. +## Development mode -The page will reload if you make edits. You will also see any lint errors in the console. +To start the development mode run `yarn run dev`. If not configured otherwise the development mode will run in mock-mode which +emulates a hedgedoc backend. +If you want to use the development with a real hedgedoc backend then run `yarn run dev:for-real-backend` instead. +The app should run now and be available under [http://localhost:3001](http://localhost:3001) in your browser. +In development mode the app will autoload changes you make to the code. -### Tests +## Production mode -#### Unit +Use `yarn build` to build the app in production mode and save it into the `.next` folder. The production build is minimized +and optimized for best performance. Don't edit them by hand! + +You can run the production build using the built-in server with `yarn start`. +You MUST provide the environment variable `HD_EDITOR_BASE_URL` with protocol, domain and (if needed) path ( +e.g. `http://127.0.0.1:3001/`) so the app knows under which URL it is available in the browser. +Optionally you can also provide `HD_RENDERER_BASE_URL` if the renderer should use another domain than the editor. This is +recommended for security reasons but not mandatory. + +### Production mock build + +It is also possible to create a production build that uses the emulated backend by using `yarn build:mock`. + +## Using to backend and frontend together + +To use backend and frontend together you'll need a reverse proxy that combines both services under one URL origin. +We provide a configuration for [caddy](https://caddyserver.com/) in the directory `dev-reverse-proxy`. + +1. Make sure that the backend is running on port `3000` (which is the default), and that `HD_DOMAIN` is set + to `http://localhost:8080`. +2. Start the frontend by using either running `yarn dev:for-real-backend` or by running a production build + with `HD_EDITOR_BASE_URL` set to `http://localhost:8080/`. +3. Start the reverse proxy. You can use the script `run-caddy.sh` in the `dev-reverse-proxy` directory or download a + caddy binary from [caddy](https://caddyserver.com/) and start it using `caddy run`. + +## Running Tests + +### Unit Unit testing is done via jest. 1. Run `yarn test` -#### End2End +### End2End We use [cypress](https://cypress.io) for e2e tests. -1. Start the frontend with `yarn dev:test` in dev test mode or build a test build with `yarn build:test` which you can - serve with `yarn serve:build` - Don't use the regular start/build command, or the tests will fail! +1. Start the frontend with `yarn dev:test` (or use a test build using `yarn build:test` which you can start + using `yarn start`). The usage of `:test` is mandatory! 2. Run `yarn cy:open` to open the cypress test loader -3. Choose your browser and test -4. Let the tests run +3. Choose your browser and start a test suite + +To run all tests in a headless browser use `yarn cy:run:chrome` or `yarn cy:run:firefox` ### Bundle analysis You can inspect the generated production-bundle files to look for optimization issues. -1. Run `yarn analyze` +1. run `yarn analyze`. This will overwrite any existing builds! 2. Open the generated `.next/server/analyze/server.html` in your favourite browser - -## Production mode - -1. Clone this repo (e.g. `git clone https://github.com/hedgedoc/react-client.git hedgedoc-react-client`) -2. Go inside the repo (e.g. `cd hedgedoc-react-client`) -3. Run `yarn install` -4. Run `yarn build` - -This will build the app in production mode and save it into the `.next` folder. The production build is optimized for -best performance, minimized and the filenames include a hash value of the content. Don't edit them by hand! - -You can run the production build using the built-in server with `yarn start`. -You MUST provide the environment variable `HD_EDITOR_BASE_URL` with protocol, domain and (if needed) path (e.g. `http://127.0.0.1:3001/`) so the app knows under which URL it is available in the browser. -You can also provide `HD_RENDERER_BASE_URL` if the renderer should use another domain than the editor. This is recommended for security reasons but not mandatory. - -## UI Test - -Curious about the new look and feel? We provide a demo of the new UI on [hedgedoc.dev](https://hedgedoc.dev). This version uses mocked data and has no data persistence. - -The UI test is hosted by [netlify](https://netlify.com). Please check their [privacy policy](https://netlify.com/privacy) as well as [ours](https://hedgedoc.org/privacy-policy). diff --git a/dev-reverse-proxy/README.md b/dev-reverse-proxy/README.md deleted file mode 100644 index 80992804e..000000000 --- a/dev-reverse-proxy/README.md +++ /dev/null @@ -1,12 +0,0 @@ - - -To use backend and frontend together you need a reverse proxy that combines both services under one URL origin. - -We provide a ready to use config for caddy. -Make sure that the backend is running on port 3000 with the env var HD_DOMAIN set to `http://localhost:8080` and the frontend is running on port 3001 with the env var HD_EDITOR_BASE_URL set to `http://localhost:8080/`. - -You can either use the script `run-caddy.sh` in this directory or download a caddy binary from [caddy](https://caddyserver.com/) and start it using `caddy run`. diff --git a/package.json b/package.json index 1e85bfd11..82d9f1b04 100644 --- a/package.json +++ b/package.json @@ -6,7 +6,7 @@ "build": "cross-env NODE_ENV=production next build", "build:mock": "cross-env NEXT_PUBLIC_USE_MOCK_API=true next build", "build:test": "cross-env NODE_ENV=test NEXT_PUBLIC_TEST_MODE=true next build", - "analyze": "cross-env ANALYZE=true next build", + "analyze": "cross-env ANALYZE=true yarn build", "dev": "cross-env PORT=3001 next dev", "dev:test": "cross-env PORT=3001 NODE_ENV=test NEXT_PUBLIC_TEST_MODE=true next dev", "dev:for-real-backend": "cross-env PORT=3001 NEXT_PUBLIC_USE_MOCK_API=false HD_EDITOR_BASE_URL=http://localhost:8080/ next dev",