1
0
Fork 0
mirror of https://github.com/hedgedoc/hedgedoc.git synced 2025-01-10 04:51:52 +00:00

fix(docs): Restructure README.md

Signed-off-by: Tilman Vatteroth <git@tilmanvatteroth.de>
This commit is contained in:
Tilman Vatteroth 2022-10-02 21:59:42 +02:00
parent 88b5e88c75
commit 6b35f16738
3 changed files with 53 additions and 53 deletions

View file

@ -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).

View file

@ -1,12 +0,0 @@
<!--
SPDX-FileCopyrightText: 2022 The HedgeDoc developers (see AUTHORS file)
SPDX-License-Identifier: CC-BY-SA-4.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`.

View file

@ -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",