diff --git a/development.md b/development.md new file mode 100644 index 0000000..b0299dd --- /dev/null +++ b/development.md @@ -0,0 +1,38 @@ +# Development guide + +This project uses React framework with Typescript. +It uses Webpack to manage module bundles and assets. + +## Project structure + +All high-level development configurations (e.g. typescript, babel, and eslint) are in their own dedicated files in project root. + +The project has a `pre-commit` hook that prevents committing changes that violate typing and linting configs. +To check if the code passes the checks, run `npm run lint` and `npx tsc`. Running `npm run lint:fix` will try to fix the issues that can be resolved automatically. + +### Webpack + +All webpack configs are in `webpack.*.js`. + +Some dependencies like `maplibre` are bundled through their own entry in `entry` config to help with chunk size. + +Browser polyfills (`src/polyfill.js`), global styling of the app (`src/styles/main.scss`), and global config (`src/config.js`) are loaded directly using their own dedicated entry in webpack. + +The HTML entrypoint is `src/index.html`, which is loaded by `webpack-html-plugin`. Any global asset or remote resources (e.g. fonts) can be added here. The transpiled React code is injected into this file by webpack. + +`webpack.dev.js` is used with `start` script in `package.json` for development, and `webpack.prod.js` is used with `build` script. + +### Code + +Description of main files under `src` folder. + +| file/folder | description | +|-------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| app.tsx | The main entrypoint. It sets up the app, routing, default styling and themes, and some localizations.
It also fetches some permanent data that is needed from the API in a `React.useEffect` hook.
The rest of the data are fetches on-demand. | +| routes.tsx | Contains routes config. This config is used in `app.tsx` | +| store/context.ts | Uses React Context to store the data describing the state of the app, and functions for updating it. | +| store/reducers.ts | Reducers are functions that update the state stored in the context with the data received from dispatchers. | +| store/states.ts | The initial state of the app. | +| store/api.ts | Helper functions to interact with the API. | +| types/* | Typescript types | +| components/* | React components | diff --git a/src/components/Home/index.tsx b/src/components/Home/index.tsx index 21f93b8..96c8654 100644 --- a/src/components/Home/index.tsx +++ b/src/components/Home/index.tsx @@ -281,7 +281,7 @@ const Home = (): JSX.Element => ( }} variant="h2" > - The World's First Expedition of the Deep Sea + The World's First Exploration of the Deep Sea import('./components/Home')); +/** + A mapping of routes to `RouteProps`. + The required property for each route is `element`, which must be a valid React component. + + This mapping is used in `src/app.tsx` to set up all the routes. + * */ const routes: { [key: string]: import('react-router-dom').RouteProps } = { '/': { element: ( diff --git a/src/store/contexts.ts b/src/store/contexts.ts index eaefc35..3a27b78 100644 --- a/src/store/contexts.ts +++ b/src/store/contexts.ts @@ -1,3 +1,9 @@ +/** + * Various context storage that hold data and functions that can be used by different components. + * These are accessible in any place in the app that `React.useContext` can be used. + * For clarity, data and dispatchers (functions that update the state) are store in separate contexts. + */ + import React from 'react'; import { dataStateInitialValue, filtersStateInitialValue } from './states';