Merge branch 'main' into dfs-list-p

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
   `<type>/official/<name>/` or `<type>/community/<scope>/<name>/`) onto base
   files (located in `<type>/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
 ```