Ionic 8 Playground
A playground project for Ionic 8 with React.
Helpful Hints
Data
This project's API integration uses the simulated REST endpoints made available by JSON Placeholder.
Authentication
When running the application, you may sign in with any of the JSON Placeholder Users. Simply enter the Username value from any user in the API and use any value for the Password. For example, try username Bret and password abc123.
Easter Eggs
Diagnostics
Many applications, particularly mobile applications, have a hidden page which displays content useful for troubleshooting and support. To access the diagnostics page, go to the Account page. Locate the About section and click or tap the Version item 7 times.
About
This project was bootstrapped with the Ionic CLI.
ionic start ionic8-playground blank --type=react
The technology stack includes:
- Ionic - the foundation
- Vite - React development environment
- React - SPA framework
- React Router Dom - routing
- TanStack React Query - data manipulation and caching
- Axios - http client
- Formik - form management
- Yup - validation
- Lodash - utility functions
- DayJS - date utility functions
- i18next - internationalization framework
- Testing Library React - unit tests
- Vitest - unit tests
- MSW - API mocking
- Cypress - end-to-end tests
- TypeScript
Repository
This repository uses trunk-based development. The latest code is located on the main branch. The main branch is always ready for deployment.
Features are developed on branches named feature/NNNNN which are created from the main branch. The feature name used in the branch contains an issue identifier or a short name, e.g. feature/123-do-something.
Releases are created on branches named release/MM.mm.pp which are created from the main branch. The release name follows the semantic versioning specification.
Hotfixes are created on branches named release/MM.mm.pp which are created from the appropriate release/MM.mm.pp branch.
A pull request must be opened requesting merge from any branch back to main. GitHub actions perform continuous integration, CI, checks against the PR source branch. At least one code review approval is required to complete the pull request.
See also: Feature flags
Issue Management
This project uses GitHub Issues.
Code Formatting
The project includes a configuration file for the Prettier code formatter. This allows all project contributors to share the same code formatting rules.
Adjust the Prettier configuration as desired.
Installation
Prerequistes
It is strongly recommended that you install Node Version Manager, nvm. Node Version Manager simplifies working on multiple projects with different versions of Node.js.
Clone the Repository
Open the repository in a browser. Follow the instructions to clone the repository to your local machine.
Install Node
Open a terminal window and navigate to the project base directory. Issue the following command to install the version of Node and NPM used by the application:
# If you already have this version of Node, simply switch to it...
nvm use
# If you do NOT have this version of Node, install it...
nvm install
Node Version Manager inspects the .nvmrc file in the project base directory and uses or installs the specified version of Node and the Node Package Manager, npm.
Install the Dependencies
To install the project dependencies, issue the following commands at a terminal prompt in the project base directory:
# Switch to the project node version...
nvm use
# Install project dependencies
npm install
After Installation
The installation is now complete! You may open the project in your favorite source code editor (we recommend Visual Studio Code).
We recommend the following VS Code extensions:
- Prettier - Code formatter (required)
- ESLint - Source code analysis (strongly recommended)
- Ionic (optional)
- Indent Rainbow (optional)
- GitLens (optional)
- Dotenv Official +Vault (optional)
- GitHub Actions (optional)
Install the Prettier extension to ensure that all project participants' contributions are formatted using the same rules. The extension leverages project-specific rules found in the .prettierrc file in the project base directory.
Configuration
The application is configured using Environment Variables. Because single-page applications are static, environment variable values are injected into the application during the build. The environment variables may be sourced from the environment or .env files as described in the Vite documentation.
NOTE: Ionic Config provides a way to change the properties of Ionic components globally. This is different from application configuration. See the Ionic Config docs for more details.
.env files
NOTE: Because they may contain sensitive information,
.envfiles are not committed to the repository.
TIP: When configuration values are modified, notify your DevOps team to modify the values in automation pipelines accordingly.
After project installation and before running the application locally, create the following .env files in the project base directory. Learn more in the official Vite guide for environment variables and modes.
.env.local
The .env.local configuration file provides the configuration values when the application is started on a developer's local machine.
# Provided by Pipeline (Simulated)
VITE_BUILD_DATE=1970-01-01
VITE_BUILD_TIME=00:00:00
VITE_BUILD_TS=1970-01-01T00:00:00+0000
VITE_BUILD_COMMIT_SHA=local
VITE_BUILD_ENV_CODE=local
VITE_BUILD_WORKFLOW_NAME=local
VITE_BUILD_WORKFLOW_RUN_NUMBER=1
VITE_BUILD_WORKFLOW_RUN_ATTEMPT=1
# API Configuration
VITE_BASE_URL_API=https://jsonplaceholder.typicode.com
# Toasts Configuration
VITE_TOAST_AUTO_DISMISS_MILLIS=5000
.env.test.local
The .env.test.local configuration file provides configuration values used when tests are executed on a developer's local machine.
NOTE: Use the same values when running tests in a CI/CD pipeline.
# Provided by Pipeline (Simulated)
VITE_BUILD_DATE=1970-01-01
VITE_BUILD_TIME=00:00:00
VITE_BUILD_TS=1970-01-01T00:00:00+0000
VITE_BUILD_COMMIT_SHA=test
VITE_BUILD_ENV_CODE=test
VITE_BUILD_WORKFLOW_NAME=test
VITE_BUILD_WORKFLOW_RUN_NUMBER=1
VITE_BUILD_WORKFLOW_RUN_ATTEMPT=1
# API Configuration
VITE_BASE_URL_API=https://jsonplaceholder.typicode.com
# Toasts Configuration
VITE_TOAST_AUTO_DISMISS_MILLIS=1500
Available Scripts
Many of the scripts leverage the Ionic CLI, the Vite CLI, or the Vitest CLI. Read more about them in their respective official guides.
In the project base directory, the following commands are available to run.
npm run dev
Runs the app in the development mode. Open http://localhost:5173 to view it in the browser.
The page will reload if you make edits.
npm test
Launches the test runner in the interactive watch mode. See the section about running tests for more information.
npm run test:coverage
Runs the test suites once and produces a coverage report. A detailed test coverage report is created in the ./coverage directory.
npm run test:ci
Executes the test runner in CI mode and produces a coverage report. With CI mode enabled, the test runner executes all tests one time and prints a summary report to the console. A code coverage report is printed to the console immediately following the test summary.
A detailed test coverage report is created in the ./coverage directory.
NOTE: This is the command which should be utilized by CI/CD platforms.
npm run test:e2e
Runs all end-to-end (e2e) tests using the Cypress framework. See the Cypress CLI documentation for more information.
npm run build
Builds the app for production to the dist folder.
It correctly bundles in production mode and optimizes the build for the best performance.
See the official guide for more information about building for production and deploying a static site.
npm run lint
Runs the ESLint static code analysis and prints the results to the console.
DevOps
Cloud Resources
The AWS resources for this application component are provisioned via AWS CloudFormation. The template.yml file is the CloudFormation template.
The resources provisioned are:
| Resource | Description |
|---|---|
| S3 Bucket | Contains the published application. |
| S3 Bucket Policy | Provides access to the S3 Bucket from AWS CloudFront. |
| CloudFront Distribution | A CloudFront distribution to serve the SPA application. |
| CloudFront Distribution | A CloudFront distribution to serve the full-stack application (UI, API, etc). |
| Route53 RecordSet | An A record for the application distribution. |
| Route53 RecordSet | An AAAA record for the application distribution. |
CI/CD Pipelines
This project uses GitHub Actions to perform DevOps automation activities such as Continuous Integration and Continous Deployment. See all project GitHub Actions workflow runs.
| Workflow | Trigger | Description |
|---|---|---|
| CI | Pull Request for main branch |
Builds, lints, and tests the application. Validates the AWS CloudFormation template. |
| Deploy to Development | Push to main branch |
Deploys AWS CloudFormation stack. Builds and deploys the application. |
| Deploy to QA | Push to release/* branch |
Deploys AWS CloudFormation stack. Builds and deploys the application. |
| Deploy to Production | Publish a Release | Deploys AWS CloudFormation stack. Builds and deploys the application. |
Related Information
