You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+52-39Lines changed: 52 additions & 39 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -16,22 +16,22 @@ Everything is written in **TypeScript** and runs on **Node.js**.
16
16
The frontend is **React** via **Next.js** and deployed in **Docker containers** on an **AWS Elastic
17
17
Container Service** cluster.
18
18
19
-
The backend is an **Express** app deployed as an **AWS Lambda** function using **AWS Cloud Development Kit**. It connects to an **AWS DynamoDB** instance that is also configured through
19
+
The backend is an **Express** app deployed as an **AWS Lambda** function using **AWS Cloud
20
+
Development Kit**. It connects to an **AWS DynamoDB** instance that is also configured through
20
21
**Terraform**.
21
22
22
23
The app uses **AWS Cognito** (through **AWS Amplify**) to handle authentication for registered
23
24
users. Unregistered users are able to browse the site in guest mode without saving their data to the
24
25
DynamoDB database.
25
26
26
-
We deploy using
27
-
**[GitHub Actions ](https://github.com/newjersey/navigator.business.nj.gov/actions)** for
28
-
CI/CD.
27
+
We deploy using **[GitHub Actions](https://github.com/newjersey/navigator.business.nj.gov/actions)**
28
+
for CI/CD.
29
29
30
30
## Development
31
31
32
32
You will need Node.js (with Yarn installed via `npm` or `corepack`) installed for primary
33
-
development. Additionally, for running the server in local development mode, you will need
34
-
Python (for the AWS CLI and some of our scripts) installed (details below).
33
+
development. Additionally, for running the server in local development mode, you will need Python
34
+
(for the AWS CLI and some of our scripts) installed (details below).
35
35
36
36
We recommend using WSL2 if developing on Windows.
37
37
@@ -43,9 +43,11 @@ For pair programming, we recommend Visual Studio Code with the Live Share extens
43
43
[nvm](https://github.com/nvm-sh/nvm#readme) for managing Node.js versions. If installing via
44
44
package manager, we suggest installing `corepack` if available separately.)
45
45
-[Docker](https://www.docker.com/) — required for running containers locally
46
-
-**macOS:** We recommend using [Colima](https://github.com/abiosoft/colima) as your Docker runtime
46
+
-**macOS:** We recommend using [Colima](https://github.com/abiosoft/colima) as your Docker
- You can manually configure Colima with `colima start --edit` or the script `install.sh` will configure automatically.
49
+
- You can manually configure Colima with `colima start --edit` or the script `install.sh` will
50
+
configure automatically.
49
51
-**Windows (WSL2):** Use Docker Desktop with WSL2 integration enabled
50
52
-**Linux:** Use the native Docker Engine installation
51
53
-[AWS CLI](https://aws.amazon.com/cli/)
@@ -67,8 +69,8 @@ You will then setup your AWS credentials:
67
69
aws configure
68
70
```
69
71
70
-
Clone the code and navigate to the root of this repository. There is an installation script that will
71
-
install all required development tools, yarn packages, and execute a yarn build.
72
+
Clone the code and navigate to the root of this repository. There is an installation script that
73
+
will install all required development tools, yarn packages, and execute a yarn build.
72
74
73
75
```shell
74
76
./scripts/install.sh
@@ -81,13 +83,17 @@ Before you can run locally, you will need to:
81
83
- create a `./web/.env` that includes all the values laid out in the `./web/.env-template` file.
82
84
- create a `./api/.env` that includes all the values laid out in the `./api/.env-template` file.
83
85
- create a `.venv` virtual environment and install requirements if working on Python
84
-
-_Note: The application does not need a venv. This step is only required to run Python helper scripts._
86
+
-_Note: The application does not need a venv. This step is only required to run Python helper
87
+
scripts._
88
+
85
89
```shell
86
90
python3 -m venv .venv
87
91
source .venv/bin/activate
88
92
pip install -r requirements.txt
89
93
```
94
+
90
95
- do an initial build (skip if you ran `install.sh`)
96
+
91
97
```shell
92
98
yarn build
93
99
```
@@ -142,33 +148,38 @@ yarn test:python
142
148
143
149
### Running locally
144
150
145
-
Before starting the app, make sure your Docker environment is running. This is required for DynamoDB Local.
151
+
Before starting the app, make sure your Docker environment is running. This is required for DynamoDB
152
+
Local.
146
153
147
-
_Note:_ If you ran the `install.sh` script, you should have Colima installed and running on your machine already. The script also sets Colima as a service for Homebrew to start on machine login.
154
+
_Note:_ If you ran the `install.sh` script, you should have Colima installed and running on your
155
+
machine already. The script also sets Colima as a service for Homebrew to start on machine login.
148
156
149
157
#### First-Time Setup
150
158
151
-
You will need to have all dependencies installed. If you haven't done so, you can install all required technologies by running `./scripts/install.sh` from the root directory.
159
+
You will need to have all dependencies installed. If you haven't done so, you can install all
160
+
required technologies by running `./scripts/install.sh` from the root directory.
152
161
153
162
1. Build the application
154
163
155
-
```shell
156
-
yarn build # This happens in the install.sh script as well.
157
-
```
164
+
```shell
165
+
yarn build # This happens in the install.sh script as well.
166
+
```
158
167
159
168
2. Launch all the services
160
169
161
-
```shell
162
-
yarn start:dev
163
-
```
170
+
```shell
171
+
yarn start:dev
172
+
```
164
173
165
-
3. Open the application in your browser. The frontend is available at [localhost:3000](http://localhost:3000)
174
+
3. Open the application in your browser. The frontend is available at
175
+
[localhost:3000](http://localhost:3000)
166
176
167
-
4. Terminate the application with `Ctrl+C`. A cleanup script will tear down the Docker processes. If you need to stop the Docker containers manually, run:
177
+
4. Terminate the application with `Ctrl+C`. A cleanup script will tear down the Docker processes. If
178
+
you need to stop the Docker containers manually, run:
168
179
169
-
```shell
170
-
yarn services:down
171
-
```
180
+
```shell
181
+
yarn services:down
182
+
```
172
183
173
184
### Deploying
174
185
@@ -178,8 +189,8 @@ Use `ship-it` to run prettier, linting, and tests before pushing:
178
189
./scripts/ship-it.sh
179
190
```
180
191
181
-
The GitHub CI/CD (which is configured in `.github/workflows`) will pick up the job and deploy
182
-
to the development environment for commits to the main branch.
192
+
The GitHub CI/CD (which is configured in `.github/workflows`) will pick up the job and deploy to the
193
+
development environment for commits to the main branch.
183
194
184
195
## Frontend deep-dive
185
196
@@ -201,8 +212,8 @@ line in `_app.tsx`).
201
212
For Next.js, environment variables are inserted at build time. In `./web/next.config.js`, the
202
213
environment variables that the code will have access to are set up for the Next.js framework by
203
214
pulling them in from the `.env` file. This works because the system that is building the Next.js
204
-
code (via GitHub Actions workflow) has access to these variables via environment variables set during that
205
-
build step.
215
+
code (via GitHub Actions workflow) has access to these variables via environment variables set
216
+
during that build step.
206
217
207
218
**Important**: This means that any time you build the app, the system building it (your local
208
219
terminal, for example) needs to have these environment variables set as well, or else they will not
@@ -253,14 +264,15 @@ make use of the `useUserData` wrapper around this hook.
253
264
254
265
## Backend deep-dive
255
266
256
-
The backend code lives in `./api`. It uses [AWS Cloud Development Kit (CDK)](https://docs.aws.amazon.com/cdk/v2/guide/home.html) for
257
-
handling the integration with AWS Lambdas.
267
+
The backend code lives in `./api`. It uses
268
+
[AWS Cloud Development Kit (CDK)](https://docs.aws.amazon.com/cdk/v2/guide/home.html) for handling
269
+
the integration with AWS Lambdas.
258
270
259
-
We use CDK to deploy the backend app. The backend app itself is defined in`api/src/functions/express/app.ts` and is mostly a regular Express app,
260
-
except it wraps its export in `serverless-http` to become a handler. Locally, the Express app runs normally.
261
-
API gateway routing is configured using AWS CDK in the `api/cdk/lib/apiStack.ts` file, which
262
-
defines the config structure that proxies all routes through to be handled by the Express routing
263
-
system.
271
+
We use CDK to deploy the backend app. The backend app itself is defined in
272
+
`api/src/functions/express/app.ts` and is mostly a regular Express app, except it wraps its export
273
+
in `serverless-http` to become a handler. Locally, the Express app runs normally. API gateway
274
+
routing is configured using AWS CDK in the `api/cdk/lib/apiStack.ts` file, which defines the config
275
+
structure that proxies all routes through to be handled by the Express routing system.
264
276
265
277
The rest of the code is regular hexagonal Express structure. The `src/api` folder contains route
266
278
definitions and depends on abstractions and types defined in `src/domain`. The `src/db` folder
@@ -354,10 +366,11 @@ Business.NJ.gov is an open source project that is meant to serve as a base for a
354
366
to create an online resource for their own business community. You can find full license details at
0 commit comments