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: rachel@remix.run
• 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.

Vitest

For lower level tests of utilities and individual components, we use vitest. We have DOM-specific assertion helpers via @testing-library/jest-dom.

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.