diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8c64e830a..a4dfd924b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,37 +1,131 @@ # Contributing -To get started, clone the repo, run `npm i`, and then `npm run src:build` (or -`npm run src:watch`). We use TypeScript, so code must be compiled before it -runs. +## Getting Started + +To get started, clone the repo, and install dependencies: + +```bash +npm i +``` + +Then build using: + +```bash +npm run src:build +``` + +or build and watch for changes using: + +```bash +npm run src:watch +``` + +> [!NOTE] +> We use TypeScript, so the code must be compiled before it runs. ## Generating You can generate the starters by running: ```bash -npm run starters:build +npm run starters:build -- --current ``` You can build a single starter by specifying the path: ```bash -npm run starters:build -- angular/official/tabs +npm run starters:build -- angular/official/tabs --current ``` * Starters are generated by overlaying starter files (located in `/official//` or `/community///`) onto base files (located in `/base/`) into the `build/` directory. -* Unless the `--current` flag is passed to the build command, base files are - checked out from which ever revision the starter requires (called the - starter's `baseref`). +* If the `--current` flag is not passed to the build command, the base files will + be checked out from the value of the `baseref`. * The `baseref` is defined in the starter's manifest file, which is a special - file that invokes additional operations on the generated starter files. + file that invokes additional operations on the generated starter files. [Example manifest file](https://github.com/ionic-team/starters/blob/7bcf9aa56289f36a5f03ed24bed76ba8c3ac89fe/vue/official/list/ionic.starter.json#L3). + +## Previewing + +You can preview the starters by navigating to the `build` directory and running `ls` to find the name of the starter you want to preview: + +```bash +cd build/ +ls +``` + +The commands to serve the app differ slightly based on the framework. View each framework's commands below. + +### Angular + +Navigate into the starter's directory, install dependencies, then serve the app: + +```bash +cd angular-official-list/ +npm i +npm run start +``` + +> [!NOTE] +> Navigate to http://localhost:4200/ in your browser to preview the app. + +### React + +Navigate into the starter's directory, install dependencies, then serve the app: + +```bash +cd react-official-list/ +npm i +npm run start +``` + +> [!NOTE] +> The browser will automatically open a tab and navigate to http://localhost:3000/ to preview the app. + +### React Vite + +Navigate into the starter's directory, install dependencies, then serve the app: + +```bash +cd react-vite-official-list/ +npm i +npm run dev +``` + +> [!NOTE] +> The URL to preview the app defaults to http://localhost:5173/ unless that port is in use. The exact URL will be displayed after running the dev server. + +### Vue + +Navigate into the starter's directory, install dependencies, then serve the app: + +```bash +cd vue-official-list/ +npm i +npm run serve +``` + +> [!NOTE] +> Navigate to http://localhost:8080/ in your browser to preview the app. + +### Vue Vite + +Navigate into the starter's directory, install dependencies, then serve the app: + +```bash +cd vue-vite-official-list/ +npm i +npm run dev +``` + +> [!NOTE] +> The URL to preview the app defaults to http://localhost:5173/ unless that port is in use. The exact URL will be displayed after running the dev server. ## Testing You can test starters by running: -``` +```bash npm run starters:test ```