2020-11-22 15:50:07 -05:00
|
|
|
<!--
|
2021-01-06 15:37:59 -05:00
|
|
|
SPDX-FileCopyrightText: 2021 The HedgeDoc developers (see AUTHORS file)
|
2020-11-22 15:50:07 -05:00
|
|
|
|
|
|
|
|
SPDX-License-Identifier: CC-BY-SA-4.0
|
|
|
|
|
-->
|
|
|
|
|
|
2020-09-02 15:17:26 -04:00
|
|
|
# HedgeDoc - React Client
|
2020-05-14 09:41:38 -04:00
|
|
|
|
2020-12-22 11:27:26 -05:00
|
|
|
|
|
|
|
|
|
|
|
|
|
|
2021-10-07 15:19:07 -04:00
|
|
|
[](https://lgtm.com/projects/g/hedgedoc/react-client/context:javascript)
|
|
|
|
|
[](https://lgtm.com/projects/g/hedgedoc/react-client/alerts/)
|
2020-07-16 05:22:53 -04:00
|
|
|
|
2022-10-02 15:59:42 -04:00
|
|
|
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).
|
2020-05-14 09:41:38 -04:00
|
|
|
|
2020-06-06 17:58:45 -04:00
|
|
|
## Preparation
|
2021-12-25 10:44:24 -05:00
|
|
|
|
2022-06-15 14:40:26 -04:00
|
|
|
You need at least Node 14 (we recommend Node 18) and [yarn](https://yarnpkg.com/).
|
2022-07-30 17:32:19 -04:00
|
|
|
You MUST use yarn! There is no support for npm.
|
2020-05-14 09:41:38 -04:00
|
|
|
|
2020-12-22 11:27:26 -05:00
|
|
|
1. Clone this repo (e.g. `git clone https://github.com/hedgedoc/react-client.git hedgedoc-react-client`)
|
2020-09-02 15:17:26 -04:00
|
|
|
2. Go inside the repo (e.g. `cd hedgedoc-react-client`)
|
2020-08-04 15:29:17 -04:00
|
|
|
3. Run `yarn install`
|
2020-05-14 09:41:38 -04:00
|
|
|
|
2022-10-02 15:59:42 -04:00
|
|
|
## Development mode
|
2020-05-14 09:41:38 -04:00
|
|
|
|
2022-10-02 15:59:42 -04:00
|
|
|
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.
|
2020-05-14 09:41:38 -04:00
|
|
|
|
2022-10-02 15:59:42 -04:00
|
|
|
## Production mode
|
2020-07-16 05:22:53 -04:00
|
|
|
|
2022-10-02 15:59:42 -04:00
|
|
|
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!
|
2020-07-16 05:34:56 -04:00
|
|
|
|
2022-10-02 15:59:42 -04:00
|
|
|
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.
|
2020-07-16 05:34:56 -04:00
|
|
|
|
2022-10-02 15:59:42 -04:00
|
|
|
### Production mock build
|
2020-07-16 05:34:56 -04:00
|
|
|
|
2022-10-02 15:59:42 -04:00
|
|
|
It is also possible to create a production build that uses the emulated backend by using `yarn build:mock`.
|
2020-07-16 05:22:53 -04:00
|
|
|
|
2022-10-02 15:59:42 -04:00
|
|
|
## Using to backend and frontend together
|
2020-07-16 05:22:53 -04:00
|
|
|
|
2022-10-02 15:59:42 -04:00
|
|
|
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`.
|
2020-07-16 05:22:53 -04:00
|
|
|
|
2022-10-02 15:59:42 -04:00
|
|
|
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`.
|
2021-12-25 10:44:24 -05:00
|
|
|
|
2022-10-02 15:59:42 -04:00
|
|
|
## Running Tests
|
2020-09-20 17:22:37 -04:00
|
|
|
|
2022-10-02 15:59:42 -04:00
|
|
|
### Unit
|
2020-09-20 17:22:37 -04:00
|
|
|
|
2022-10-02 15:59:42 -04:00
|
|
|
Unit testing is done via jest.
|
2020-05-14 09:41:38 -04:00
|
|
|
|
2022-10-02 15:59:42 -04:00
|
|
|
1. Run `yarn test`
|
2021-12-25 10:44:24 -05:00
|
|
|
|
2022-10-02 15:59:42 -04:00
|
|
|
### End2End
|
2020-05-14 09:41:38 -04:00
|
|
|
|
2022-10-02 15:59:42 -04:00
|
|
|
We use [cypress](https://cypress.io) for e2e tests.
|
2022-01-11 09:59:03 -05:00
|
|
|
|
2022-10-02 15:59:42 -04:00
|
|
|
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 start a test suite
|
2022-01-11 09:59:03 -05:00
|
|
|
|
2022-10-02 15:59:42 -04:00
|
|
|
To run all tests in a headless browser use `yarn cy:run:chrome` or `yarn cy:run:firefox`
|
|
|
|
|
|
|
|
|
|
### Bundle analysis
|
2022-01-11 09:59:03 -05:00
|
|
|
|
2022-10-02 15:59:42 -04:00
|
|
|
You can inspect the generated production-bundle files to look for optimization issues.
|
|
|
|
|
|
|
|
|
|
1. run `yarn analyze`. This will overwrite any existing builds!
|
|
|
|
|
2. Open the generated `.next/server/analyze/server.html` in your favourite browser
|
