ElectrifyDC

This is the Civic Tech DC repo for the Electrify DC website project.

Tools we use

• Language: TypeScript
• Deployment: Fly app deployment with Docker
  • Healthcheck endpoint for Fly backups region fallbacks
• Database: SQLite Database
  • ORM: Prisma
• CI/CD: GitHub Actions
• Email/Password Authentication with cookie-based sessions
• Styling: Tailwind
• End-to-end testing: Cypress
• Local third party request mocking: MSW
• Unit testing: Vitest and Testing Library
• Code formatting: Prettier
• Linting: ESLint

Development

Create your own untracked .env file

This sets some necessary environment variables and allows you to add your own environment variables in a file that is ignored by git.

cp .env.example .env

Developing locally on MacOS

Install Nodejs

You'll need to have Nodejs installed locally. See .tool-versions for the version.

I use asdf to manage my tool versions but you could also use n, nvm, or specific versions of Nodejs.

Install dependencies

npm install

Run the setup script

The setup script sets up the database, runs any pending migrations, and seeds the database with some starter data.

npm run setup

Start the dev server

This starts your app in development mode, rebuilding assets on file changes. It will run at localhost:3000.

npm run dev

Developing locally with Docker

Install Docker

You'll need to have Docker Desktop installed and running.

Build the Docker image

docker-compose build

Run the Docker image

Now you can run the Docker image with Docker Compose. It will run at localhost:3000. Docker Compose will share your local application files with the Docker container using a volume so that as you change application files they should also automatically update inside the Docker container and be reloaded by the web server.

docker-compose up

If you want it to run in the background you can add the -d flag. If you do you can view logs with docker-compose logs app.

The app comes with a test-user pre-configured

• Email: [email protected]
• Password: racheliscool

Connecting to a deployed database

The sqlite database lives at /data/sqlite.db in your deployed application. You can connect to the live database by running fly ssh console -C database-cli.

GitHub Actions

We use GitHub Actions for continuous integration and deployment. Anything that gets into the main branch will be deployed to staging after running tests/build/etc. Anything in the prod branch will be deployed to production.

Read more about DEPLOYING.

Testing

Cypress

We use Cypress for our End-to-End tests in this project. You'll find those in the cypress directory. As you make changes, add to an existing file or create a new file in the cypress/e2e directory to test your changes.

We use @testing-library/cypress for selecting elements on the page semantically.

To run these tests in development, run npm run test:e2e:dev which will start the dev server for the app as well as the Cypress client. Make sure the database is running in docker as described above.

We have a utility for testing authenticated features without having to go through the login flow:

cy.login();
// you are now logged in as a new user

We also have a utility to auto-delete the user at the end of your test. Just make sure to add this in each test file:

afterEach(() => {
  cy.cleanupUser();
});

That way, we can keep your local db clean and keep your tests isolated from one another.

Type Checking

This project uses TypeScript. It's recommended to get TypeScript set up for your editor to get a really great in-editor experience with type checking and auto-complete. To run type checking across the whole project, run npm run typecheck.

Linting

This project uses ESLint for linting. That is configured in .eslintrc.cjs.

Formatting

We use Prettier for auto-formatting in this project. It's recommended to install an editor plugin (like the VSCode Prettier plugin) to get auto-formatting on save. There's also a npm run format script you can run to format all files in the project.

Content Management System

We use Decap-CMS as a content management system. This allows users who belong to the GitHub repository to sign into a special /admin/ portal to edit any content that is managed by the CMS.

There is a specific deployed environment where the CMS system is enabled. In other environments it is disabled. It is also enabled in local environments, but you must run the CMS server separately for it to work correctly.

The Content Environment

The content environment is deployed at https://repower-dmv-content.fly.dev/. The CMS admin panel is located at https://repower-dmv-content.fly.dev/admin/ (note: the trailing slash is important! /admin will not work).

The content environment is deployed from the cms-content-updates branch and changes made in the content environment are committed to the cms-content-updates branch. When new changes are committed they will trigger a new deployment and after a few minutes the changes will be visible in the application.

The Decap-CMS backend is configured in app/content/content-backend.yml.

CMS in Local Development

The CMS is also enabled for local development but it runs with a different backend than in deployed environments. In order for it to function correctly you must be running the Decap server locally:

npx decap-server

If you are prompted for a username and password when you try to use the CMS admin panel locally you probably aren't running the Decap server.

The Decap-CMS backend is configured in app/content/local-backend.yml.

Implementation and Configuration

The implementation is somewhat complicated so it's described here:

• There are custom routes implemented for the /admin/ and /admin/config.yml paths. They have logic which checks the DEPLOY_ENV environment variable and if it is not set to one of local or content then they simply return 404. This is the case for all deployed environments except for the content environment.
• /admin/ path:
  • when DEPLOY_ENV is set to content or local, returns some static HTML which then serves the DecapCMS frontend from a CDN cache. The HTML is copy/pasted from the Decap-CMS setup docs.
• /admin/config.yml path:
  • If the DEPLOY_ENV value is set to content then app/content/content-backend.yml is merged with app/content/config.yml and returned.
  • If the DEPLOY_ENV value is set to local then app/content/local-backend.yml is merged with app/content/config.yml and returned.

Managing Content in the CMS

In order for content to be managed by the CMS it needs to be configured. That means:

1. Making sure the information architecture is defined in app/content/config.yml.
2. Storing the content strings in a JSON file inside the app/content/ directory.
3. Where the content is used in the application, import it from the relevant JSON file using the appropriate key. You can import entire JSON files like this: import content from "../content/apply.json";