The SeaSketch Next client application is built using create-react-app. It's architecture is typical of a single-page-app and uses the SeaSketch Next GraphQL API for data persistence.
git clone https://github.com/seasketch/next.git
cd next/packages/client
npm install
cp .env.template .env
npm startIf you need to run locally using SSL, you'll need to setup the environment properly for both the api server and the client.
Localization is managed using i18next. Wrap all strings in appropriate tags so they can be translated into multiple languages. ESLint rules will flag missing tags.
We're using a public POEditor project to manage translations. Local npm scripts exist to publish new terms to this project and extract translations into the client/src/lang directory. Run npm run translation:sync to perform these operations. It is important to do this regularly. The CI system will build a newly updated clients, but will only include new translations if this step is performed and changes are checked in.
Terms are organized into namespaces, each with their own translation file. Currently only a subset of namespaces are published to the POEditor project to be translated. Originally SeaSketch Next is being launched to support ocean use surveys so we are only translating the public side of the survey functionality.
To add new namespaces as new features are launched, edit client/src/lang/namespaces.json.
To add new supported languages, add required metadata to client/src/lang/supported.ts. You will also need to add a matching entry to the POEditor project using their GUI.
The client will connect to the GraphQL endpoint specified by the REACT_APP_GRAPHQL_ENDPOINT environment variable. An Apollo Client context is provided to all React components. Using Visual Studio Code and the Apollo GraphQL plugin, you should see IntelliSense hints when authoring queries based on the generated GraphQL schema found in packages/api/generated-schema.gql.
While authoring queries and handling data you should run the graphql:codegen npm script. This script will watch for changes in React components and generate types for GraphQL queries, as well as custom hooks. These can be found in src/generated/graphql.ts. Beware they can be a bit slow to be picked up by the TypeScript server in VSCode, so you may want to visit the graphql.ts file manually. Queries should be placed in src/queries/*.graphql (not co-located in components).
SeaSketch Next doesn't use a pre-made component library. Instead, common components should go in src/components/*.tsx. Reusable UI elements currently include Switch, Button, and TextInput components. Be sure to document components thouroughly using jsdoc conventions and provide examples using storybook.
The Tailwind CSS framework is included and used for styling custom components. Use Tailwind UI when developing the user interface to develop a consistent look and feel.
- Use react-router-dom to manage routes
- Use React.lazy to create code-splitting boundaries where necessary.
Start an automated deployment using a pull request.
In the project directory, you can run:
Runs the app in the development mode.
Open http://localhost:3000 to view it in the browser.
The page will reload if you make edits.
You will also see any lint errors in the console.
Launches the test runner in the interactive watch mode.
See the section about running tests for more information.
Builds the app for production to the build folder.
It correctly bundles React in production mode and optimizes the build for the best performance.
Extract i18n identifiers and place in ./extractedTranslations.
Generates types from gql template tags and stores them in src/generated/graphql.ts.
Starts a storybook server on localhost:8080 where documentation and examples for reusable components can be referenced.