packs

Packs survey generator tool 🕊

Packs is a command-line tool for developing and bundling React-based survey components with a declarative format. The cli tool utilizes the packs-framework to package components into a single-page application.

Installation

It's recommended to install packs within each survey project directory as a development dependency for better version control. (Yarn is the recommended package manager to ensure deterministic lockfiles, but npm also works fine).

yarn add -D packs

Then you can specify commands from your package.json scripts field for local development, building and testing your survey:

{
  "scripts": {
    "start": "packs --serve",
    "build": "packs --build",
    "test": "packs --test",
    "deploy": "packs --deploy"
  }
}

Directory structure

Your survey project must include a /modules directory and a survey.json configuration file. The project may include an /images directory with optional images that are used throughout the survey in MarkDown texts.

The /modules directory should only include indexed module JSON files which will be ordered according to the filesystem ordering. Run packs --rename to update the module file names based on their index and any necessary leftpadding.

Each module JSON file must specify a survey component package / name and any module parameters, e.g.:

{
  "component": "packs-components/Markdown",
  "body": "# Hello, World 🌍"
}

Make sure each survey components package is installed, e.g. to install common components from packs-components.

yarn add packs-components

Your survey.json file must specify a survey name, component and wrapper package dependencies (which must also be installed under /node_modules) as well as an initialState object, if required.

{
  "name": "your-survey",
  "components": ["packs-components", "your-survey-components"],
  "wrapper": "your-survey-wrapper",
  "initialState": {
    "counter": 0
  }
}

Local development

To run a survey locally at http://localhost:9000:

yarn start

Any changes to your module JSON files or survey.json file will be reflected on browser reload. Under the hood, packs uses webpack-dev-middleware to lazy load and package your survey components.

Building

To build static files for deployment under ./public/index.html and ./public/app.js with minification and production flags, run:

yarn build

Testing

After building static files you can test module responses and state with:

yarn test

Packs will run the Component.simulate method for each survey component to simulate response states for each module and the whole survey.

Survey versioning

It's required that you use git for version control of your survey project or else your builds will fail. Packs will use the hash of your latest commit, e.g. abcd123, which it will suppy to a survey through the initialState object under the surveyVersion field. If you named your survey your-survey, then packs will supply the following fields to your survey:

{
  "surveyName": "your-survey",
  "surveyVersion": "abcd123"
}

If you are running the survey locally, or you have uncommited changes in your directory, then packs will append -local and -changed to your surveryVersion respectively.

Deployment to S3

yarn deploy

The script deploy files to S3 bucket in the following order: bucketName/surveyName/surveyVersion The script assumes the user run build before deploy (the script assumes that there are "public" and ".packs" directories in the running path) The script searches for file "aws.json" in the running path and all the directory above.

The format of "aws.json" is

{
"bucketName": "your Bucket Name",
"accessKeyId": "your Access Key Id",
"secretAccessKey": "your Secret Access Key"
}

Compiling

You can easily deploy and manage a survey project using GitLab CI / Pages, without requiring collaborators to install additional local dependencies beyond git or a GitLab account.

For example, the following gitlab-ci.yml file will build, publish and test the survey with GitLab Pages:

image: node:8

pages:
  cache:
    paths:
    - node_modules/

  script:
  - yarn install --frozen-lockfile
  - yarn build
  - yarn test
  artifacts:
    paths:
    - public
  only:
  - master

Version History

3.3.3

• update packs-framework version

3.3.2

• wrap the components by numbers instead of lettes, to enable more than 26 components

3.3.1

• Tidy up - remove lib/ from git, use tslint.

3.3.0

• Add deployment to Amazon S3

3.2.5

• Remove minifications that cause issues on Windows and Gitlab's CI

3.2.4

• Uploaded to npm with LF line endings (CRLFs caused a problem for Gitlab's CI)

3.2.3

• Pack images from the image directory, so they can be referenced by surveys.
• Serve images from the image directory when running packs --serve

3.2.0 - 3.2.2

Attempts of making version 3.2.3 that eventually failed.

3.1.2

Last version by Robbie