- General Information
- Quick Start Guide - Start Here!
- Testing Packages Locally - Test packages before they are released or merged.
- Directory Structure - How the repo is designed.
- Git Aliases - Available git aliases.
- Scripts - Scripts for running and working on the web app.
This application will be used to showcase the code, packages, and services that the Common Code team offers. It will also serve as a testing grounds for packages before new versions are published.
- Running on a NodeJS:20 with React, and Express.
-
Create a
.envfile based on theexample.envfile. -
Run
npm run upto start the app locally.
Packages such as @bcgov/citz-imb-sso-react and @bcgov/citz-imb-sso-express can be tested within the Showcase app before they are merged and released. This means you can make changes to these package repos on your local machine, and then see these changes reflected within the Showcase app.
- The following package repos must be cloned to your machine in the same directory as this repo:
@bcgov/citz-imb-sso-react - SSO React package. @bcgov/citz-imb-sso-express - SSO Express package. @bcgov/citz-imb-sso-css-api - SSO CSS API package. @bcgov/citz-imb-endpoint-builder - Endpoint Builder package.
- You must run the
npm run buildcommand from each of these package repo directories. - To see changes in the Showcase app, you must rebuild using the
npm run up:overrideornpm run rebuild:overridescripts.
This works because the compose.override.yaml file sets volume mounts that map the build directory in each package repo to the corresponding node_modules folder.
Any time changes are made that you want reflected in the Showcase app, you will need to build the package and run npm run rebuild in this directory.
Since this mapping is done through docker, you may get type errors in your IDE because the IDE sees the version of the package in the package.json, but docker is building with the contents of the build directory from the package repo directory.
.
├── .github/
| ├── config/
| | └── dep-report.json5 # Configure options for NPM Dep Report.
| ├── helpers/
| | ├── github-api/ # Functions to access the GitHub API.
| | ├── create-npm-dep-report-issues.js # Creates GitHub Issues for Npm Dep Reports.
| | ├── create-npm-dep-report.js # Creates text bodies for Npm Dep Reports.
| | ├── parse-json5-config.js # Parses json5 files for GitHub actions output.
| | └── parse-npm-deps.js # Parses package.json files for changes to package versions.
| ├── workflows/
| | └── npm-dep-report.yaml # Reports on new package versions.
├── src/
| ├── backend/ # Express API.
| | ├── scripts/ # Utility scripts used to run the server.
| | ├── src/
| | | ├── modules/ # Modules of functionality (routes, controllers, entities, services).
| | | └── utils/ # Utility functions for the express api.
| | ├── express.ts # Express configuration and base route configuration.
| | ├── index.ts # Server initialization.
| | └── package.json # Configure packages.
| ├── frontend/ # React.
| | ├── src/
| | | ├── assets/ # Images.
| | | ├── components/
| | | | └── common/ # Common or reusable visual components.
| | | ├── css/ # Base styles and variables.
| | | ├── pages/ # Page components.
| | | ├── AppRouter.tsx # Router for loading pages at routes.
| | | ├── global.d.ts # Global type declarations (used for config endpoint).
| | | └── main.tsx # Main JavaScript run in index.html.
| | ├── index.html # Set web app meta data and title.
| | ├── nginx.conf # Configure proxy pass for prod build.
| | ├── package.json # Configure packages.
| | └── vite.config.ts # Configure vite server and proxy pass for dev build.
These aliases are available within the repository after using the following setup command:
# Sets git aliases.
$ npm run setup-git-aliases# List all available aliases.
$ git list-aliases# Amend staged changes to the last commit without changing the commit message.
$ git amend# Undo the last commit and bring it's changes back into the staging area.
$ git undo-last-commit-soft# Undo the last commit and discard it's changes.
$ git undo-last-commit-hard# See files changed in relation to main branch.
$ git changes# Start the web app (ensure env vars set).
$ npm run up# Start the web app (ensure env vars set).
# Volume mounts the build directories of external packages to node_modules within docker,
# so that local package repos can be tested within the app.
#
# See 'Testing Packages Locally' before using.
$ npm run up:override# Stop the web app.
$ npm run down# Prune all containers, images and volumes. Clears docker cache.
$ npm run prune# Clean install packages in frontend and backend (requires prune and up to affect live site).
$ npm run install# Clean install packages in frontend (requires prune and up to affect live site).
$ npm run install:frontend# Clean install packages in backend (requires prune and up to affect live site).
$ npm run install:backend# Prunes, clears docker cache, clean installs packages, and rebuilds containers.
$ npm run rebuild# Prunes, clears docker cache, clean installs packages, and rebuilds containers.
# Uses `npm run up:override` instead of `npm run up`.
#
# See 'Testing Packages Locally' before using.
$ npm run rebuild:override# Shell into frontend container.
# Type 'exit' + ENTER to exit shell.
$ npm run shell:frontend# Shell into backend container (used when working with migrations).
# Type 'exit' + ENTER to exit shell.
$ npm run shell:backend# Clear docker cache.
$ npm run clear-docker-cache# Sets git aliases.
$ npm run setup-git-aliases