Quiz-react-sdk NPM

id: quiz-react-sdk

             _                           _             _ _
  __ _ _   _(_)____  _ __ ___  __ _  ___| |_   ___  __| | | __
 / _` | | | | |_  / | '__/ _ \/ _` |/ __| __| / __|/ _` | |/ /
| (_| | |_| | |/ /  | | |  __/ (_| | (__| |_  \__ \ (_| |   <
 \__, |\__,_|_/___| |_|  \___|\__,_|\___|\__| |___/\__,_|_|\_\
    |_|

The Quiz React SDK is a collection of React components and tools for building applications built on top of the Instructure Quiz API service.

Getting Started

First, install all of the Docker prerequisites (VirtualBox, Docker, Dinghy/Dory):

https://github.com/instructure/canvas-lms/blob/stable/doc/docker/getting_docker.md

Now you're ready to spin up the SDK docs application for development:

bin/dev-setup
docker-compose up -d
open http://quiz.docker

Using Local Development Quiz API

The default development environment for the SDK uses a prebuilt docker image of the Quiz API service. While working on the SDK, you will likely find that it's necessary to hook it up with a local development version of the service.

In your quiz_api repository, edit your docker-compose.override.yml to enable integration seeds. It should look something like this:

# For SDK integration tests:
      - ../quiz_web/integration:/usr/src/app/demo

Now run the integration seeds in your quiz_api environment:

bin/seed-sdk-data.sh

Those seeds create a JSON config file that is uploaded to S3. In order to consume the config data quiz_web needs access to this url.

Back in your quiz_web checkout, enable the CONFIG_URL setting in your docker-compose.override.yml for the web and integration containers, by uncommenting the following line in both locations:

CONFIG_URL: http://quiz.s3.docker/docs_app_uploads/sdk-demo/(development|test).config.json

Additionally, you need to update the KINESIS_ENDPOINT setting on both containers to use the following:

KINESIS_ENDPOINT: http://kinesis.docker/

Now restart your web (and integration) container(s) if they are already running:

docker-compose restart web integration

If you are developing quiz_web without docker, add the url to env:

export CONFIG_URL=http://quiz.s3.docker/docs_app_uploads/sdk-demo/development.config.json

and start the server and go to localhost:8080

yarn run start

Running without Docker

While it's highly recommended you install and use Docker to work on the SDK, there are a couple things that are more difficult to do within Docker, and you may want to run the webpack-dev-server for the docs app outside of Docker. This is often desired for better support of filesystem watchers, and for linking development checkouts of NPM package dependencies.

Currently, the following versions of Node and Yarn are required:

Node: 9.11.1 or later
Yarn: 1.6.0 or later

With Node and Yarn installed, spin up webpack-dev-server locally by running:

yarn start

You can access the docs application at: http://localhost:8080

Staying Updated

Anytime your pull the latest changes to the SDK, you must also download the latest NPM packages, and rebuild your docker images. This can be done like so:

git pull
bin/dev-update

If a standard dev-update is still giving you trouble, run bin/table-flip to clear out some npm junk that might be getting in the way. It won't clear out any of your data since we're just dealing with quiz_web here, so it's safe to run without worrying too much about side effects.

Testing with local quiz-interactions

To override the quiz-interactions node module with a local copy, uncomment the following line in your docker.compose.override.yml, making sure the path actually points to where you have the quiz_interactions project on your machine.

- ../quiz_interactions/__build__:/usr/src/app/node_modules/quiz-interactions

In order for there to actually be something in quiz_interactions/__build__ (which is what actually gets pulled in), you'll need to run either yarn build or yarn build:watch in the quiz_interactions project.

After making those changes, you will need to restart the web container in order for it to pick up the changes to the docker.compose.override.yml.

Creating a new Quiz Session

The default setup creates a handful of quizzes and established sessions for them. If you want to make a new one, you can run the quiz_session:create rake task in quiz_api. This defaults to using a quiz id of 1 but you can change this by issuing the command as quiz_session:create QUIZ_ID=5 or similar.

cd ../quiz_api/
docker-compose run --rm web bundle exec rake quiz_session:create QUIZ_ID=3

Contributing

Commit Messages

We have some special tooling in place around commit messages. Please see the committing docs for more details.

Code Formatting

We are using EditorConfig to help with code formatting. You should enable support for EditorConfig in your favorite code editor.

Linting

Run yarn run lint to lint the src dir.

We are using ESLint.

You might want to install this git pre-push hook to automatically lint changes:

cp hooks/pre-push.example .git/hooks/pre-push

You might need to globally install a few eslint packages, depending on your environment. Here's a start:

yarn global add eslint babel-eslint eslint-config-standard{,-react} \
  eslint-plugin-{format-message,react,mocha,standard,promise}

Internationalization

Any string that needs I18n will use formatMessage so that yarn can extract those strings. If you have added any strings that you expect to be internationalized to the project, be sure to run docker-compose run —rm web yarn run extract to have yarn extract the I18n strings.

Sublime Setup

If you use Sublime Text for your code editor, we recommend the following:

Install the following plugins:

Install NPM packages locally outside of Docker: yarn install
Restart Sublime Text

Styles

The app uses css modules with postcss. 'styles/variables.js' defined variables which are automatically added to css files using the postcss-simple-vars loader. If you add/change a variable, in order to see the change you'll need to rerun webpack and restart the dev server.