To get started, clone the repo, and install dependencies:
npm i
Then build using:
npm run src:build
or build and watch for changes using:
npm run src:watch
Note
We use TypeScript, so the code must be compiled before it runs.
You can generate the starters by running:
npm run starters:build -- --current
You can build a single starter by specifying the path:
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 thebuild/
directory. - If the
--current
flag is not passed to the build command, the base files will be checked out from the value of thebaseref
. - The
baseref
is defined in the starter's manifest file, which is a special file that invokes additional operations on the generated starter files. Example manifest file.
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:
cd build/
ls
The commands to serve the app differ slightly based on the framework. View each framework's commands below.
Navigate into the starter's directory, install dependencies, then serve the app:
cd angular-official-list/
npm i
npm run start
Note
Navigate to http://localhost:4200/ in your browser to preview the app.
Navigate into the starter's directory, install dependencies, then serve the app:
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.
Navigate into the starter's directory, install dependencies, then serve the app:
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.
Navigate into the starter's directory, install dependencies, then serve the app:
cd vue-official-list/
npm i
npm run serve
Note
Navigate to http://localhost:8080/ in your browser to preview the app.
Navigate into the starter's directory, install dependencies, then serve the app:
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.
You can test starters by running:
npm run starters:test
You can test a single starter by specifying the starter ID (also the starter's
directory name within the build/
directory):
npm run starters:test -- angular-official-tabs
- Starters must be generated before they can be tested. The test command works
with starters generated in the
build/
directory. - To test a starter, first the dependencies are installed (
npm install
), and then thescripts.test
key in the starter's manifest file is executed. This way, each starter can define how it must be tested.
The starter manifest file (named ionic.starter.json
) is a required JSON file
at the root of the starter. The build process reads the manifest and takes
actions based upon what's defined in the file.
Key | Description |
---|---|
name |
The human-readable name. |
baseref |
The latest git ref (branch or sha) at which the starter is compatible with the base files (located in <type>/base/ ). |
welcome |
(optional) A custom message to be displayed when the user runs ionic start on the starter. See Starter Welcome. |
gitignore |
(optional) During build, the defined array of strings will be added to the bottom of the project's .gitignore file. |
packageJson |
(optional) During build, the defined keys will be recursively merged into the generated package.json . |
tsconfigJson |
(optional) During build, the defined keys will be recursively merged into the generated tsconfig.json . |
tarignore |
(optional) During deploy, the defined array of strings will be interpreted as globs to ignore files to include in the tar file when deployed. |
scripts |
(optional) An object of scripts that run during build or deploy. |
scripts.test |
(optional) During test, after dependencies are installed, the defined script will be executed to test the starter. |
To submit your own starter,
-
Fork this repo.
-
Fork or copy the Example Starter.
-
Add a git submodule for your starter at
<type>/community/<your github name>/<github repo name>
. For example:git submodule add https://github.com/ionic-team/starter-example.git ionic-angular/community/ionic-team/example
-
Build your starter. For example:
npm run starters:build -- ionic-angular/community/ionic-team/example
-
Copy the generated starter into a different directory and test it!
To update your starter,
- Push changes to your starter repo freely.
- Run
git pull
in your starters fork directory (ionic-angular/community/ionic-team/example
for example). - Commit the changes to your fork and create a PR.
Tips:
- When you
cd
into a git submodule directory (i.e.ionic-angular/community/ionic-team/example
), git commands operate on the submodule as its own repository. - Inside a submodule folder,
git remote add local /path/to/starter/at/local
will add a new git remote which you can use to pull local changes in. Make commits in your local starter repo, thengit pull local
. - New commits in a submodule must also be saved in the base repository for PRs.
- Don't include a
.gitignore
file. If you need to ignore some files in your starter repo, you can use the private gitignore file located at.git/info/exclude
. If you need to add entries, you can use thegitignore
key in your manifest file.
For a custom message to be displayed for your starter during ionic start
, you
can set the welcome
key of your starter manifest file to a string. For
terminal colors and other formatting, you can create a quick script to generate
the message, JSON-encode it, and copy it into your manifest file. See this
example
script
for the Super Starter.
Starters are deployed automatically when new commits are pushed to the master
branch.
During the deploy process, the build/
directory is read and an archive of each
generated starter is created and gzipped and uploaded to an S3 bucket. The S3
bucket has a CloudFront distribution for close-proximity downloads. The
distribution ID is E1XZ2T0DZXJ521
and can be found at this
URL.
First, make sure you pull down the latest community starter submodules by running:
git pull --recurse-submodules
If you have not already initialized the submodules locally run:
git submodule update --init --recursive
Then run:
npm run starters:deploy
You can use npm run starters:deploy -- --dry
to test the tar process.
By default, starters are deployed to the testing
"tag" (latest
is
production). You can install tagged starters by specifying the --tag=<tag>
option to ionic start
).
Note you will need permissions to the S3 bucket to manually deploy