A template to kickstart Ionic + React applications utilizing an opinionated technology stack for optimal testability, maintainability, and operability.
Â
Â
This project is licensed under the MIT License - see LICENSE file for details.
For detailed guides and reference materials, see the Project Documentation.
This project's API integration uses the simulated REST endpoints made available by JSON Placeholder.
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.
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.
This project was bootstrapped with the Ionic CLI.
ionic start ionic8-starter blank --type=react
The application production technology stack includes:
- Ionic - the foundation
- Vite - React development environment
- React - SPA framework
- React Router Dom - routing
- TanStack Query - data fetching, caching, and asynchronous state management
- Axios - HTTP client
- Formik - form management
- Yup - schema-based validation (deprecated)
- Zod - schema-based validation
- Lodash - utility functions
- DayJS - date utility functions
- i18next - internationalization framework
The application development technology stack includes:
- Vitest - unit tests
- Testing Library React - unit tests
- MSW - API mocking
- Cypress - end-to-end tests
- TypeScript
The infrastructure technology stack includes:
- AWS CDK - framework for provisioning AWS cloud infrastructure
- Zod - schema based validation
- Jest: unit test framework
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
This project uses GitHub Issues.
The project includes configuration files for the Prettier and EditorConfig code formatters. This allows all project contributors to share the same code formatting rules.
Adjust the configuration as desired.
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.
Open the repository in a browser. Follow the instructions to clone the repository to your local machine.
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 installNode 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.
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 installThe 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 (recommended)
- GitHub Copilot (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.
See the Configuration Guide in the project docs for detailed information about application and infrastructure configuration.
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.
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.
Launches the test runner in the interactive watch mode. See the section about running tests for more information.
Runs the test suites once and produces a coverage report. A detailed test coverage report is created in the ./coverage directory.
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.
Runs all end-to-end (e2e) tests using the Cypress framework. See the Cypress CLI documentation for more information.
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.
Runs the ESLint static code analysis and prints the results to the console.
See the DevOps Guide in the project docs for detailed information about DevOps automation workflows.
See the Infrastructure Guide in the project docs for detailed information about the AWS infrastructure and the AWS CDK application to provision those resources.