Developing with Pushkin

Pushkin is 100% open-source. We love it when people come together to help fix bugs, build features, and make Pushkin better for everyone. If you’d like to contribute, feel free to open a pull request. The Pushkin project is split into several repos, each corresponding to a an NPM module. Issues and general project direction is tracked via GitHub’s project boards and issues. An example of all of them working together is available via the pushkin generate command. Below is a general overview.

1. Client (Docs) A module that provides simplified methods for making calls to a Pushkin API and unpacking data sent back from a worker. Note that built-in functions assume the API has corresponding default routes enabled to handle such requests.

2. API (Docs) Essentially a mini-server designed with the use case of interfacing between Pushkin Client and Pushkin Worker via RabbitMQ.

3. CLI (Docs) Installable via NPM. Adds a pushkin command to the path when installed globally and makes working with Pushkin much easier.

4. Worker (Docs) Receives messages from RabbitMQ and runs whatever functionality it’s told to run, sending the result back through the queue it came from. Designed to be on the receiving end of a Pushkin API. Comes with built-in simple functions that most users will probably want, like “getAllStimuli”.

5. JSPsych (Docs) The Pushkin JSPsych repo simply makes a few small changes to the official JSPsych library so that it can be bundled together as if it’s an NPM module. In order for it to be globally accessible to plugins as they expect, the import must be assigned to window.jsPsych.

Getting Started on Development

Understanding the Front End

  1. Basics. You’ll want a reasonably thorough grounding in Javascript and React. The tutorials in Code Academy are pretty good, though not free.
  2. Pushkin is a Single Page Application (SPA) based on React. For a gentle introduction to this stack, read this tutorial, which also describes incorporating authentication with auth0. Note that this tutorial is slightly out of date in that auth0 now uses auth0-spa-js for SPAs, and create-react-app suggests using function components rather than class components.
  3. To fill in your understanding of React, we recommend the two-part Codecademy.com Learn ReactJS course.
  4. Next, you probably want to learn more about routing using React-Router. We use v5, which is nearly identical to v4. If you read up on React Router, you’ll see a lot of discussion of dynamic routing, though you can probably safely ignore this. One of the better tutorials available is here, though it’s a bit short.
  5. You’ll also want to understand Redux better. Redux is used to keep track of application-level state variables. For Pushkin, a primary usecase is keeping track of subject IDs. The best tutorial we’ve found for React-Redux is the official one. Note that it’s a little out-of-date with regards to use of object spread syntax (which is now supported by Node) and with how to handle asynchronous requests: we’ll be using redux sagas for that, so read up on that as well. A good place to start on why redux sagas are worth using is here.
  6. At this point, we recommend going back through the tutorial in #2 above.

Understanding Docker

There are a number of tutorials on Docker. For ongoing use, this cheatsheet is pretty useful.

Testing Pushkin Modules Locally

Currently, the most convenient way to test new version of Pushkin modules locally is getting the tarball of the pushkin modules you modified and putting it into the node test project folder.

  1. If you have a node project for test the new version of Pushkin modules(pushkin-api, pushkin-client, pushkin-worker, etc.), create a folder in the project dir named “testPackages”.

  2. Get the tarball of the pushkin modules to be tested, like “pushkin-api-1.2.0.tgz”. Put this tarball into the testPackages folder.

  3. Modify the package.json file in the project dir like this:

    "dependencies": {
    "pushkin-api": "file:testPackages/pushkin-api-1.2.0.tgz",
    ... ...
    }

That is, modify the path of the Pushkin module to the local test version, so that the npm will find it locally rather than the npm library

  1. npm install all the dependencies, then you can write the test codes.