The Charity

TheCharity is an open-source, non-profit web application created by the FullstacksJS community.

CONTRIBUTING

Development of TheCharity happens in GitHub, and we appreciate contributions. Learn how you can help improve TheCharity by reading the sections below.

Project Glossary

To have a better knowledge of the project domain, please read the Project Glossary.

Non-functional Requirements

Non-functional requirements

Prerequisite:

• POSIX-compliant shell
• git >= 2
• volta >= 1

Branch Organization

• main: latest stable release
• dev: latest development changes

Sending a Pull Request

The FullstacksJS team is monitoring for pull requests. We will review your pull request and either merge it, request changes to it, or close it with an explanation.

Before submitting a pull request, please make sure the following is done:

• Fork/Clone the repository and create your feature branch from dev.
• Run pnpm install to have all dependencies and husky hooks needed for development.
• Run pnpm run codegen to have latest API types.
• To start development run pnpm start.
• If you've fixed a bug or added code that should be tested, add tests, please.
• Create a PR (You can use ./scripts/pr to create one).

Envs

• APP_GRAPHQL_SCHEMA_URL: a valid URL string for graphql path used in graphql tooling.
• APP_API_ENDPOINT: a valid URL or path for the GraphQL API used in the application.
• APP_AUTH0_DOMAIN: a valid URL string for auth0 domain, more info here.
• APP_AUTH0_AUDIENCE: an OAuth2.0 audience, more info here.
• APP_AUTH0_CLIENT_ID: a valid URL string for auth0 clientId, more info here.
• APP_HASURA_ADMIN_SECRET: Hasura admin secret.
• API_PROXY_TARGET: the API target proxy URL for the dev environment.
• PORT: Optional port for running vite dev server, if not provided, will fallback to 3000.
• HOST: Optional host for running the vite dev server.
• CY_RECORD_VIDEO: Optional A boolean variable for Cypress video recording (default=true).
• OPEN: Open the browser on the dev server start (default=false).

Note: if you want to add a new environment variable to use in client you should prefix it with APP_.

recognized env files:

• .env.dev: the env file used for the dev environment

Architecture

The project contains multiple modules which have their specific responsibilities and rules. Here you can find a big picture of the code architecture and its dependencies and for more detail, you refer to the README file of each module.

An arrow from ModuleA to ModuleB means ModuleA depends on ModuleB

Scripts

Run

To start the app first set the envs as described in the envs section then run:

pnpm install
pnpm run codegen
pnpm run dev

If you're using VSCode you can install the Apollo Graphql extension to get features like autocomplete in your graphql queries

Codegen

This project uses GraphQL Code Generator to generate types and interfaces from our API schema. This ensures type safety in our operations and queries, reducing the risk of errors and improving the overall quality of our code.

to generate the latest type from the API you need to have (a proper environment)[#Envs] in place and run:

pnpm run codegen

Verify

The verify command runs all tests to make sure that your changes are working.

Build

To build the app just run:

pnpm run build

Lint

To run the linter to auto-fix all the problems run:

pnpm run lint

Test

To run the unit tests run:

pnpm run test:unit

To run e2e tests you need to have the dev server running at configured port and run:

pnpm run test:e2e

If you want only to run a specific e2e test based on a pattern you can run the test:e2ep command:

pnpm run test:e2ep [PATTERN]

if the pattern matches more than one file it will still run all of them, for example, the following command will run the createHousehold.cy.ts and householdList.cy.ts test

pnpm run test:e2ep household

To run component tests run:

pnpm run test:component

Storybook

Storybook is used for sandbox development and UI regression testing. It enables us to build and test UI components in isolation, speeding up development and reducing errors.

To run the storybook dev server run:

pnpm run storybook

Spell Check

To find spelling errors just run

pnpm run spell

And if you want to add a new word so that it won't count as a spelling error, just add it to the configs/cspell/charity.en.txt or configs/cspell/charity.en.txt and separate it with a new line

Note: These two (linting and finding spelling errors) are run automatically on each commit and the commit won't be done if there's anything wrong, even for the commit messages, so be careful what you write as a commit message :)