diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 5684bad2..ced8fcdd 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -76,8 +76,12 @@ repos: rev: v2.7.1 hooks: - id: prettier - args: [--prose-wrap=always, --write] - exclude: website/tailwind.config.js|website/.storybook/main.js|website/.eslintrc.json + args: + [ + --prose-wrap=always, + --write, + --ignore-path=./website/.prettierignore, + ] - repo: local hooks: diff --git a/website/.prettierignore b/website/.prettierignore new file mode 100644 index 00000000..0be2a485 --- /dev/null +++ b/website/.prettierignore @@ -0,0 +1,3 @@ +.eslintrc.json +tailwind.config.js +.storybook/* diff --git a/website/src/.prettierrc.json b/website/.prettierrc.json similarity index 100% rename from website/src/.prettierrc.json rename to website/.prettierrc.json diff --git a/website/README.md b/website/README.md index a30f2754..09b40e49 100644 --- a/website/README.md +++ b/website/README.md @@ -2,8 +2,7 @@ ## Purpose -This provides a comprehensive webapp interface for LAION's Open Assistant -project. Initially it will support: +This provides a comprehensive webapp interface for LAION's Open Assistant project. Initially it will support: 1. User registration using either Discord or Email. 1. Adding responses to incomplete Open Assistant tasks. @@ -11,8 +10,7 @@ project. Initially it will support: 1. Viewing an activity leaderboard. 1. Tracking community wide updates. -This interface compliments the Discord bot and will give access to the same -underlying tasks. +This interface compliments the Discord bot and will give access to the same underlying tasks. ## Contributing @@ -22,67 +20,54 @@ This website is built using: 1. [npm](https://www.npmjs.com/): The node package manager for building. 1. [React](https://reactjs.org/): The core frontend framework. -1. [Next.js](https://nextjs.org/): A React scaffolding framework to streamline - development. -1. [Prisma](https://www.prisma.io/): An ORM to interact with a web specific - [Postgres](https://www.postgresql.org/) database. -1. [NextAuth.js](https://next-auth.js.org/): A user authentication framework to - ensure we handle accounts with best practices. -1. [TailwindCSS](https://tailwindcss.com/): A general purpose framework for - styling any component. -1. [Chakra-UI](https://chakra-ui.com/): A wide collection of pre-built UI - components that generally look pretty good. +1. [Next.js](https://nextjs.org/): A React scaffolding framework to streamline development. +1. [Prisma](https://www.prisma.io/): An ORM to interact with a web specific [Postgres](https://www.postgresql.org/) + database. +1. [NextAuth.js](https://next-auth.js.org/): A user authentication framework to ensure we handle accounts with best + practices. +1. [TailwindCSS](https://tailwindcss.com/): A general purpose framework for styling any component. +1. [Chakra-UI](https://chakra-ui.com/): A wide collection of pre-built UI components that generally look pretty good. ### Set up your environment -To contribute to the website, make sure you have the following setup and -installed: +To contribute to the website, make sure you have the following setup and installed: -1. [NVM](https://github.com/nvm-sh/nvm): The Node Version Manager makes it easy - to ensure you have the right NodeJS version installed. Once installed, run - `nvm use 16` to use Node 16.x. The website is known to be stable with NodeJS +1. [NVM](https://github.com/nvm-sh/nvm): The Node Version Manager makes it easy to ensure you have the right NodeJS + version installed. Once installed, run `nvm use 16` to use Node 16.x. The website is known to be stable with NodeJS version 16.x. This will install both Node and NPM. -1. [Docker](https://www.docker.com/): We use docker to simplify running - dependent services. +1. [Docker](https://www.docker.com/): We use docker to simplify running dependent services. ### Getting everything up and running If you're doing active development we suggest the following workflow: 1. In one tab, navigate to the project root. -1. Run `docker compose up frontend-dev --build --attach-dependencies`. You can - optionally include `-d` to detach and later track the logs if desired. +1. Run `docker compose up frontend-dev --build --attach-dependencies`. You can optionally include `-d` to detach and + later track the logs if desired. 1. In another tab navigate to `${OPEN_ASSISTANT_ROOT/website`. 1. Run `npm ci` -1. Run `npx prisma db push` (This is also needed when you restart the docker - stack from scratch). -1. Run `npm run dev`. Now the website is up and running locally at - `http://localhost:3000`. -1. To create an account, login via the user using email authentication and - navigate to `http://localhost:1080`. Check the email listed and click the - log in link. You're now logged in and authenticated. +1. Run `npx prisma db push` (This is also needed when you restart the docker stack from scratch). +1. Run `npm run dev`. Now the website is up and running locally at `http://localhost:3000`. +1. To create an account, login via the user using email authentication and navigate to `http://localhost:1080`. Check + the email listed and click the log in link. You're now logged in and authenticated. ### Using debug user credentials -You can use the debug credentials provider to log in without fancy emails or -OAuth. +You can use the debug credentials provider to log in without fancy emails or OAuth. -1. This feature is automatically on in development mode, i.e. when you run - `npm run dev`. In case you want to do the same with a production build (for - example, the docker image), then run the website with environment variable +1. This feature is automatically on in development mode, i.e. when you run `npm run dev`. In case you want to do the + same with a production build (for example, the docker image), then run the website with environment variable `DEBUG_LOGIN=true`. 1. Use the `Login` button in the top right to go to the login page. -1. You should see a section for debug credentials. Enter any username you wish, - you will be logged in as that user. +1. You should see a section for debug credentials. Enter any username you wish, you will be logged in as that user. ### Using Storybook -To develop components using [Storybook](https://storybook.js.org/) run -`npm run storybook`. Then navigate to in your browser to -`http://localhost:6006`. +To develop components using [Storybook](https://storybook.js.org/) run `npm run storybook`. Then navigate to in your +browser to `http://localhost:6006`. -To create a new story create a file named `[componentName].stories.js`. An -example how such a story could look like, see `Header.stories.jsx`. +To create a new story create a file named `[componentName].stories.js`. An example how such a story could look like, see +`Header.stories.jsx`. ## Code Layout @@ -90,12 +75,10 @@ example how such a story could look like, see `Header.stories.jsx`. All react code is under `src/` with a few sub directories: -1. `pages/`: All pages a user could navigate too and API URLs which are under - `pages/api/`. -1. `components/`: All re-usable React components. If something gets used twice - we should create a component and put it here. -1. `lib/`: A generic place to store library files that are used anywhere. This - doesn't have much structure yet. +1. `pages/`: All pages a user could navigate too and API URLs which are under `pages/api/`. +1. `components/`: All re-usable React components. If something gets used twice we should create a component and put it + here. +1. `lib/`: A generic place to store library files that are used anywhere. This doesn't have much structure yet. NOTE: `styles/` can be ignored for now. @@ -113,25 +96,20 @@ We're not really using CSS styles. `styles/` can be ignored. ## Testing the UI -Cypress is used for end-to-end (e2e) and component testing and is configured in -`./cypress.config.ts`. The `./cypress` folder is used for supporting -configuration files etc. +Cypress is used for end-to-end (e2e) and component testing and is configured in `./cypress.config.ts`. The `./cypress` +folder is used for supporting configuration files etc. - Store e2e tests in the `./cypress/e2e` folder. -- Store component tests adjacent to the component being tested. If you want to - wriite a test for `./src/components/Layout.tsx` then store the test file at - `./src/components/Layout.cy.tsx`. +- Store component tests adjacent to the component being tested. If you want to wriite a test for + `./src/components/Layout.tsx` then store the test file at `./src/components/Layout.cy.tsx`. A few npm scripts are available for convenience: -- `npm run cypress`: Useful for development, it opens Cypress and allows you to - explore, run and debug tests. It assumes you have the NextJS site running at - `localhost:3000`. -- `npm run cypress:run`: Runs all tests. Useful for a quick sanity check before - sending a PR or to run in CI pipelines. -- `npm run cypress:image-baseline`: If you have tests failing because of visual - changes that was expected, this command will update the baseline images stored - in `./cypress-visual-screenshots/baseline` with those from the adjacent +- `npm run cypress`: Useful for development, it opens Cypress and allows you to explore, run and debug tests. It assumes + you have the NextJS site running at `localhost:3000`. +- `npm run cypress:run`: Runs all tests. Useful for a quick sanity check before sending a PR or to run in CI pipelines. +- `npm run cypress:image-baseline`: If you have tests failing because of visual changes that was expected, this command + will update the baseline images stored in `./cypress-visual-screenshots/baseline` with those from the adjacent comparison folder. More can be found in the [docs of `uktrade/cypress-image-diff`](https://github.com/uktrade/cypress-image-diff/blob/main/docs/CLI.md#update-all-baseline-images-for-failing-tests). @@ -141,10 +119,9 @@ Read more in the [./cypress README](cypress/). Jest and React Testing Library are used for unit testing JS/TS/TSX code. -- Store unit test files adjacent to the file being tested and have the filename - end with `.test.ts` for non-React code or `.test.tsx` for React code. -- `npm run jest`: automatically runs tests and watches for any relevant changes - to rerun tests. +- Store unit test files adjacent to the file being tested and have the filename end with `.test.ts` for non-React code + or `.test.tsx` for React code. +- `npm run jest`: automatically runs tests and watches for any relevant changes to rerun tests. Read more in the [./src/README.md](src/README.md). @@ -152,30 +129,25 @@ Read more in the [./src/README.md](src/README.md). When writing code for the website, we have a few best practices: -1. When importing packages import external dependencies first then local - dependencies. Order them alphabetically according to the package name. -1. When trying to implement something new, check if - [Chakra-UI](https://chakra-ui.com/) has components that are close enough to - your need. For example Sliders, Radio Buttons, Progress indicators, etc. - They have a lot and we can save time by re-using what they have and tweaking - the style as needed. -1. Format everything with [Prettier](https://prettier.io/). This is done by - default with pre-submits. We currently don't have any custom settings. -1. Define functional React components (with types for all properties when - feasible). +1. When importing packages import external dependencies first then local dependencies. Order them alphabetically + according to the package name. +1. When trying to implement something new, check if [Chakra-UI](https://chakra-ui.com/) has components that are close + enough to your need. For example Sliders, Radio Buttons, Progress indicators, etc. They have a lot and we can save + time by re-using what they have and tweaking the style as needed. +1. Format everything with [Prettier](https://prettier.io/). This is done by default with pre-submits. We currently + don't have any custom settings. +1. Define functional React components (with types for all properties when feasible). ### Developing New Features -When working on new features or making significant changes that can't be done -within a single Pull Request, we ask that you make use of Feature Flags. +When working on new features or making significant changes that can't be done within a single Pull Request, we ask that +you make use of Feature Flags. -We've set up -[`react-feature-flags`](https://www.npmjs.com/package/react-feature-flags) to -make this easier. To get started: +We've set up [`react-feature-flags`](https://www.npmjs.com/package/react-feature-flags) to make this easier. To get +started: -1. Add a new flag entry to `website/src/flags.ts`. We have an example flag you - can copy as an example. Be sure to `isActive` to true when testing your - features but false when submitting your PR. +1. Add a new flag entry to `website/src/flags.ts`. We have an example flag you can copy as an example. Be sure to + `isActive` to true when testing your features but false when submitting your PR. 1. Use your flag wherever you add a new UI element. This can be done with: ```js @@ -188,29 +160,24 @@ import { Flags } from "react-feature-flags"; You can see an example of how this works by checking `website/src/components/Header/Headers.tsx` where we use `flagTest`. -1. Once you've finished building out the feature and it is ready for everyone - to use, it's safe to remove the `Flag` wrappers around your component and - the entry in `flags.ts`. +1. Once you've finished building out the feature and it is ready for everyone to use, it's safe to remove the `Flag` + wrappers around your component and the entry in `flags.ts`. ### URL Paths -To use stable and consistent URL paths, we recommend the following strategy for -new tasks: +To use stable and consistent URL paths, we recommend the following strategy for new tasks: -1. For any task that involves writing a free-form response, put the page under - `website/src/pages/create` with a page name matching the task type, such as - `initial_prompt.tsx`. -1. For any task that evaluates, rates, or ranks content, put the page under - `website/src/pages/evaluate` with a page name matching the task type such as - `rank_initial_prompts.tsx`. +1. For any task that involves writing a free-form response, put the page under `website/src/pages/create` with a page + name matching the task type, such as `initial_prompt.tsx`. +1. For any task that evaluates, rates, or ranks content, put the page under `website/src/pages/evaluate` with a page + name matching the task type such as `rank_initial_prompts.tsx`. -With this we'll be able to ensure these contribution pages are hidden from -logged out users but accessible to logged in users. +With this we'll be able to ensure these contribution pages are hidden from logged out users but accessible to logged in +users. ## Learn More To learn more about Next.js, take a look at the following resources: -- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js - features and API. +- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API. - [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial. diff --git a/website/cypress/README.md b/website/cypress/README.md index 4750cbf6..d6a2b383 100644 --- a/website/cypress/README.md +++ b/website/cypress/README.md @@ -1,24 +1,19 @@ # Component and e2e testing with Cypress -[Cypress](https://www.cypress.io/) is used for both component- and end-to-end -testing. Below there's a few examples for the context of this site. To learn -more, the -[Cypress documentation](https://docs.cypress.io/guides/getting-started/opening-the-app) -has it all. +[Cypress](https://www.cypress.io/) is used for both component- and end-to-end testing. Below there's a few examples for +the context of this site. To learn more, the +[Cypress documentation](https://docs.cypress.io/guides/getting-started/opening-the-app) has it all. -Don't get scared by the commercial offerings they offer. Their core is open -source, the cloud offering is not necesarry at all and can be replaced by CI -tooling and [community efforts](https://sorry-cypress.dev/). +Don't get scared by the commercial offerings they offer. Their core is open source, the cloud offering is not necesarry +at all and can be replaced by CI tooling and [community efforts](https://sorry-cypress.dev/). # Component testing -To write a new component test, you either create a new `.tsx` adjacent to the -component you want to test or you can use the guide presented yo you when -running `npm run cypress` which allows you to easily create the skeleton test -for an existing component. +To write a new component test, you either create a new `.tsx` adjacent to the component you want to test or you can use +the guide presented yo you when running `npm run cypress` which allows you to easily create the skeleton test for an +existing component. -If you have a `Button.tsx` component, create a file next to it called -`Button.cy.tsx` which could look like this: +If you have a `Button.tsx` component, create a file next to it called `Button.cy.tsx` which could look like this: ```typescript import React from "react"; @@ -35,28 +30,24 @@ describe("