-
Create a new public repository for your project (e.g.
new-repository
) -
Create a clone of the starter repo
git clone --single-branch https://github.com/concord-consortium/starter-projects.git new-repository
-
Update the starter repo
First, update and run the starter project:
cd new-repository npm install npm update npm start
Then, verify the project works by visiting localhost:8080 and checking for the words "Hello World". Also verify that the test suite still passes:
npm run test:full
If the updates are functional, please commit any changes to
package.json
orpackage-lock.json
back to the Starter Projects repository for future use. -
Next, re-initialize the repo to create a new history
rm -rf .git git init
-
Create an initial commit for your new project
git add . git commit -m "Initial commit"
-
Push to your new repository
git remote add origin https://github.com/concord-consortium/new-repository.git git push -u origin main
-
Open your new repository and update all instances of
starter-projects
tonew-repository
andStarter Projects
toNew Repository
. Note: this will do some of the configuration for GitHub Actions deployment to S3, but you'll still need to follow the instructions here. -
To record the cypress tests results to the cypress dashboard service:
- go to https://dashboard.cypress.io
- create a new project
- go to the settings for the project
- in the GitHub integration section choose the GitHub repo to connect this project to
- copy the record key, and create a secret in the GitHub repository's settings with the name CYPRESS_RECORD_KEY
- copy the Project ID and replace the value of
projectId
in cypress.json - To enable extra Cypress to GitHub integration:
- go to the settings of the Cypress project
- go to the "Integrations" tab
- select the GitHub repository
-
To record code coverage information to codecov.io:
- go to https://codecov.io/
- login with your GitHub credentials
- find your new repository
- go to the settings for this repository and copy the CODECOV_TOKEN, and create a secret in the GitHub repository's settings.
-
Your new repository is ready! Remove this section of the
README
, and follow the steps below to use it.
- Clone this repo and
cd
into it - Run
npm install
to pull dependencies - Run
npm start
to runwebpack-dev-server
in development mode with hot module replacement
Currently there is no trivial way to load a plugin running on a local server with http
into the online CODAP, which forces https
. One simple solution is to download the latest build_[...].zip
file from https://codap.concord.org/releases/zips/, extract it to a folder and run it locally. If CODAP is running on port 8080, and this project is running by default on 3000, you can go to
http://127.0.0.1:8080/static/dg/en/cert/index.html?di=http://localhost:3000
to see the plugin running in CODAP.
This project was bootstrapped with Create React App.
In the project directory, you can run:
Runs the app in the development mode.
Open http://localhost:3000 to view it in the browser.
The page will reload if you make edits.
You will also see any lint errors in the console.
Launches the test runner in the interactive watch mode.
See the section about running tests for more information.
Builds the app for production to the build
folder.
It correctly bundles React in production mode and optimizes the build for the best performance.
The build is minified and the filenames include the hashes.
Your app is ready to be deployed!
See the section about deployment for more information.
Note: this is a one-way operation. Once you eject
, you can’t go back!
If you aren’t satisfied with the build tool and configuration choices, you can eject
at any time. This command will remove the single build dependency from your project.
Instead, it will copy all the configuration files and the transitive dependencies (Webpack, Babel, ESLint, etc) right into your project so you have full control over them. All of the commands except eject
will still work, but they will point to the copied scripts so you can tweak them. At this point you’re on your own.
You don’t have to ever use eject
. The curated feature set is suitable for small and middle deployments, and you shouldn’t feel obligated to use this feature. However we understand that this tool wouldn’t be useful if you couldn’t customize it when you are ready for it.
You can learn more in the Create React App documentation.
To learn React, check out the React documentation.
Additional steps are required to run using HTTPS.
- install mkcert :
brew install mkcert
(install using Scoop or Chocolatey on Windows) - Create and install the trusted CA in keychain if it doesn't already exist:
mkcert -install
- Ensure you have a
.localhost-ssl
certificate directory in your home directory (create if needed, typicallyC:\Users\UserName
on Windows) and cd into that directory - Make the cert files:
mkcert -cert-file localhost.pem -key-file localhost.key localhost 127.0.0.1 ::1
- Run
npm run start:secure
to runwebpack-dev-server
in development mode with hot module replacement
Alternately, you can run secure without certificates in Chrome:
- Enter
chrome://flags/#allow-insecure-localhost
in Chrome URL bar - Change flag from disabled to enabled
- Run
npm run start:secure:no-certs
to runwebpack-dev-server
in development mode with hot module replacement
If you want to build a local version run npm build
, it will create the files in the dist
folder.
You do not need to build to deploy the code, that is automatic. See more info in the Deployment section below.
- Make sure if you are using Visual Studio Code that you use the workspace version of TypeScript.
To ensure that you are open a TypeScript file in VSC and then click on the version number next to
TypeScript React
in the status bar and select 'Use Workspace Version' in the popup menu.
Follow the instructions in this
Guide
to setup an S3 & Cloudfront distribution that can be used with GitHub actions.
See also s3_deploy.sh
, and ./github/ci.yml
.
Production releases to S3 are based on the contents of the /dist folder and are built automatically by GitHub Actions for each branch and tag pushed to GitHub.
Branches are deployed to http://starter-projects.concord.org/branch/. If the branch name starts or ends with a number this number is stripped off.
Tags are deployed to http://starter-projects.concord.org/version/.
To deploy a production release:
- Increment version number in package.json
- Create new entry in CHANGELOG.md
- Run
git log --pretty=oneline --reverse <last release tag>...HEAD | grep '#' | grep -v Merge
and add contents (after edits if needed to CHANGELOG.md) - Run
npm run build
- Copy asset size markdown table from previous release and change sizes to match new sizes in
dist
- Create
release-<version>
branch and commit changes, push to GitHub, create PR and merge - Checkout main and pull
- Create an annotated tag for the version, of the form
v[x].[y].[z]
, include at least the version in the tag message. On the command line this can be done with a command likegit tag -a v1.2.3 -m "1.2.3 some info about this version"
- Push the tag to GitHub with a command like:
git push origin v1.2.3
. - Use https://github.com/concord-consortium/starter-projects/releases to make this tag into a GitHub release.
- Run the release workflow to update http://starter-projects.concord.org/index.html.
- Navigate to the actions page in GitHub and the click the "Release" workflow. This should take you to this page: https://github.com/concord-consortium/starter-projects/actions/workflows/release.yml.
- Click the "Run workflow" menu button.
- Type in the tag name you want to release for example
v1.2.3
. (Note this won't work until the PR has been merged to main) - Click the
Run Workflow
button.
Run npm test
to run jest tests. Run npm run test:full
to run jest and Cypress tests.
Inside of your package.json
file:
--browser browser-name
: define browser for running tests--group group-name
: assign a group name for tests running--spec
: define the spec files to run--headed
: show cypress test runner GUI while running test (will exit by default when done)--no-exit
: keep cypress test runner GUI open when done running--record
: decide whether or not tests will have video recordings--key
: specify your secret record key--reporter
: specify a mocha reporter
cypress run --browser chrome
will run cypress in a chrome browsercypress run --headed --no-exit
will open cypress test runner when tests begin to run, and it will remain open when tests are finished running.cypress run --spec 'cypress/integration/examples/smoke-test.js'
will point to a smoke-test file rather than running all of the test files for a project.
Starter Projects are Copyright 2018 (c) by the Concord Consortium and is distributed under the MIT license.
See license.md for the complete license text.