---
id: quiz-core
---
```sh
             _                           _             _ _
  __ _ _   _(_)____  _ __ ___  __ _  ___| |_   ___  __| | | __
 / _` | | | | |_  / | '__/ _ \/ _` |/ __| __| / __|/ _` | |/ /
| (_| | |_| | |/ /  | | |  __/ (_| | (__| |_  \__ \ (_| |   <
 \__, |\__,_|_/___| |_|  \___|\__,_|\___|\__| |___/\__,_|_|\_\
    |_|
```

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:

```sh
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:

```yml
# For SDK integration tests:
      - ../quizzes-ui/packages/quiz-core/integration:/usr/src/app/demo
```

Now run the integration seeds in your `quiz_api` environment:

```sh
bin/seed-sdk-data.sh
```

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

Back in your `quizzes-ui` 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:

```yml
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:

```yml
KINESIS_ENDPOINT: http://kinesis.docker/
```

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

```sh
docker-compose restart web integration
```

If you are developing quizzes-ui without docker, add the url to env:

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

and start the webpack-dev-server as described in the next section.


## 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

[Node]: https://nodejs.org/
[Yarn]: https://yarnpkg.com/lang/en/docs/install/

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

```sh
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:

```sh
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.

## 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.

```sh
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](doc/committing.md) 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.

[EditorConfig]: http://editorconfig.org/

### Linting

Run `yarn run lint` to lint the src dir.

We are using [ESLint](http://eslint.org/).

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

```sh
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:

```sh
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:

1. Install the following plugins:
  - https://github.com/sindresorhus/editorconfig-sublime
  - http://sublimelinter.readthedocs.org/en/latest/
  - https://github.com/roadhump/SublimeLinter-eslint
3. Install NPM packages locally outside of Docker: `yarn install`
4. 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.

## Publishing a New Release

See doc/releases.md
