README.md

Midspace: Frontend

React web app that forms the main Midspace frontend.

✨ Bootstrapped with Create Snowpack App (CSA).

Pre-requisites

1. All other setup steps! Set up the frontend last.

Setting up

1. cd frontend
2. cp .env.example .env
3. Configure your .env file according to the Frontend Configuration section below.
4. Return to the main README for steps to generate GraphQL client code and start your local working copy.
5. Production: If using Netlify, then:
   • Once you have set up Hasura Cloud, create a Netlify account and follow the steps below.
   • in Netlify, create a new site from Git.
     • If you're not part of the core Midspace team, create and use a fork of this (clowdr-app/clowdr) repository.
     • See Deployment to Netlify for instructions.
   • go back to Auth0 and add the Netlify app url(s) to the application configuration (see instructions in root README).

UI Components, Theming, and Icons

We use Chakra UI to build accessible, consistent UIs with theming. Chakra also provides icons and a system for custom components.

GraphQL

After writing, modifying or delete a GraphQL query in the frontend, you will need to regenerate the GraphQL code. You can do this using the VSCode Task Single -- GraphQL Codegen and selecting frontend (Hasura must be running).

Local Development

Refer to the comments in the vite.config.ts file regarding server configuration. For local development, you will likely need to comment out the first set of the hmr configuration options and uncomment the second set of the hmr configuration options.

If the environment configuration changes, or for example, the package.json commands change, then you will need to restart tasks for this frontend.

Testing

We use React Testing Library (with extensions) on top of Jest for testing the frontend. This includes Continuous Integration.

You should check out the documentation for the following Jest extension libraries that we use for writing better tests:

• Accessibility: jest-axe - https://www.npmjs.com/package/jest-axe

• React Testing Library extensions:

  • @testing-library/jest-dom - https://github.com/testing-library/jest-dom

  • @testing-library/user-event - https://github.com/testing-library/user-event

  • @testing-library/react-hooks - https://github.com/testing-library/react-hooks-testing-library

    Quoting from the @testing-library/react-hooks docs:

    When to use this library

    • You're writing a library with one or more custom hooks that are not directly tied to a component
    • You have a complex hook that is difficult to test through component interactions

    When not to use this library

    • Your hook is defined alongside a component and is only used there
    • Your hook is easy to test by just testing the components using it

Production builds

• Use the VSCode (build) task: Frontend -- Production Build
• Use the VSCode task: Frontend -- Serve Production Build

Alternatively:

1. To build: frontend> pnpm build Builds a static copy of the frontend to the build/ folder using snowpack & webpack.
2. To test: frontend> pnpx serve -s build Serves the static build locally for checking.

Deployment to Netlify

The frontend can easily be deployed using Netlify:

1. Connect to GitHub, select the relevant repo and branch
2. Leave the base directory blank
3. Build command: cd ../frontend && pnpm build
4. Publish directory: frontend/build
5. Environment variables: As below

Frontend Configuration

Note: Snowpack (the build tool we use) will only include environment variables in the build which start with VITE_.

Note: Pay attention to the Netlify? column when configuring Netlify. No means 'do not add to Netlify'; Yes means 'add to Netlify'; Only means 'only add in Netlify, not locally'.

Env Var	Value	Netlify?
HASURA_ADMIN_SECRET	Admin secret (used only for GraphQL Codegen)	No
GraphQL
VITE_GRAPHQL_API_DOMAIN	The domain and port of the GraphQL server	Yes
VITE_GRAPHQL_API_SECURE_PROTOCOLS	Boolean. Default: true. Whether to use https/wss or not.	Yes
Auth0
VITE_AUTH_DOMAIN	e.g. something.eu.auth0.com	Yes
VITE_AUTH_CLIENT_ID	as shown in Auth0 Application	Yes
AWS
VITE_COMPANION_BASE_URL	URL of the Uppy Companion instance (provided at /companion by the actions service)	Yes
NPM_VERSION	7.3 (only required in Netlify)	Only
NODE_VERSION	17.4 (only required in Netlify)	Only
Vonage Video API
VITE_OPENTOK_API_KEY	API key for the Vonage Video API project
VITE_PRESENCE_SERVICE_URL	URL to the presence service.
Other
VITE_TECH_SUPPORT_ADDRESS	Email address for contacting tech support	Yes