Getting Started on Development
Last updated
Was this helpful?
Last updated
Was this helpful?
Basics. You’ll want a reasonably thorough grounding in Javascript and React. The tutorials in Code Academy are pretty good, though not free.
Pushkin is a Single Page Application (SPA) based on React. For a gentle introduction to this stack, read this , 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.
To fill in your understanding of React, we recommend the two-part Codecademy.com course.
Next, you probably want to learn more about routing using React-Router. We use , which is nearly identical to v4. If you read up on React Router, you’ll see a lot of , though you can probably safely ignore this. One of the better tutorials available is , though it’s a bit short.
You’ll also want to understand Redux better. Redux is used to keep track of application-level state variables. For Pushkin, a primary use case is keeping track of subject IDs. The best tutorial we’ve found for React-Redux is . Note that it’s a little out-of-date with regards to the use of object spread syntax (which is now supported by Node) and with how to handle asynchronous requests: we’ll be using for that, so read up on that as well. A good place to start on why redux sagas are worth using is .
At this point, we recommend going back through the tutorial in #2 above.
There are a number of tutorials on Docker. For ongoing use, this is pretty useful.
For information on running tests with Jest, see
The content on this page may be out of date - stay tuned for edits!
Currently, the most convenient way to test new versions of Pushkin modules locally is to get the tarball of the pushkin modules you modified and put it into the node test project folder.
If you have a node project for testing the new version of Pushkin modules (pushkin-api, pushkin-client, pushkin-worker, etc.), create a folder in the project dir named “testPackages”.
Get the tarball of the pushkin modules to be tested, like “pushkin-api-1.2.0.tgz”. Put this tarball into the testPackages folder.
Modify the package.json file in the project dir like this:
That is, modify the path of the Pushkin module to the local test version so that Yarn will find it locally rather than in the npm repository.
After you yarn add all of the dependencies, you can write the test codes.
If you're testing out a new version of pushkin-worker, you should have a directory with the dev version of pushkin-worker, a directory with a pushkin site you are working on, and an experiment in your site's experiments directory for which you want to try out the dev version of pushkin-worker.
Go to the root directory of your dev version of pushkin-worker.
Assuming you've cloned pushkin-worker from GitHub, it won't have any dependencies installed, so you'll need to run yarn install; yarn build.
Run yalc publish to create a locally published version of pushkin-worker.
Go to the worker directory within the experiment folder. Typically this will be [project root]/experiments/[experiment name]/worker.
Run yalc add pushkin-worker to add your locally published version of pushkin-worker as a dependency.
Open the package.json file in that same directory and add a property "files" with a value ["build/*", ".yalc"] like such:
(Note this has not been tested yet, so the array of files might need to be modified, e.g. [".yalc"])
Open the Dockerfile in that same directory and edit it to copy yalc files:
These lines need to come before the WORKDIR is changed. So for example:
(This final step is pretty well explained in the yalc README)
Now you should be able to run pushkin prep and pushkin start. When you make changes to pushkin-worker, you'll need to:
Go to the root directory of your dev version of pushkin-worker.
Run yarn build; yalc push. yalc push will update your locally published version of pushkin-worker and push the changes wherever the package is being used.
If you're testing out a new version of pushkin-api, you should have a directory with the dev version of pushkin-api, a directory with a pushkin site you are working on, and at least one experiment in your site's experiments directory.
Go to the root directory of your dev version of pushkin-api.
Assuming you've cloned pushkin-api from GitHub, it won't have any dependencies installed, so you'll need to run yarn install; yarn build.
Run yalc publish to create a locally published version of pushkin-api.
Go to the pushkin/api directory of your site.
Run yalc add pushkin-api to add your locally published version of pushkin-api as a dependency.
Go to the 'experiments/[experiment name]/api controllers' directory.
Again run yalc add pushkin-api.
Open the package.json file in that same directory.
You should see it has a property "files" with a value ["build/*"]. Add ".yalc" to the list of files like such:
You'll need to repeat steps 6 through 9 for each experiment in your site's experiments directory.
Now you should be able to run pushkin prep and pushkin start. When you make changes to pushkin-api, you'll need to:
Go to the root directory of your dev version of pushkin-api.
Run yarn build; yalc push. yalc push will update your locally published version of pushkin-api and push the changes wherever the package is being used. This saves you the hassle of running yalc update in the multiple directories in which you ran yalc add.
If you're testing out a new version of pushkin-client, you should have a directory with the dev version of pushkin-client, a directory with a pushkin site you are working on, and at least one experiment in your site's experiments directory.
Go to the root directory of your dev version of pushkin-client.
Assuming you've cloned pushkin-client from GitHub, it won't have any dependencies installed, so you'll need to run yarn install; yarn build.
Run yalc publish to create a locally published version of pushkin-client.
Go to the pushkin/front-end directory of your site.
Run yalc add pushkin-client to add your locally published version of pushkin-client as a dependency.
Go to the 'experiments/[experiment name]/web page' directory.
Again run yalc add pushkin-client.
Open the package.json file in that same directory.
You should see it has a property "files" with a value ["build/*"]. Add ".yalc" to the list of files like such:
You'll need to repeat steps 6 through 9 for each experiment in your site's experiments directory.
Now you should be able to run pushkin prep and pushkin start. When you make changes to pushkin-client, you'll need to:
Go to the root directory of your dev version of pushkin-client.
Run yarn build; yalc push. yalc push will update your locally published version of pushkin-client and push the changes wherever the package is being used. This saves you the hassle of running yalc update in the multiple directories in which you ran yalc add.
If you are working on any of the utility packages (, , or ), trying out your new code is not straightforward. These packages are included in the experiments and sites via npm. Normally, that means you can only include published versions. We can get around this using . You've probably already installed yalc if you've followed the Pushkin . If not, install yalc:
(Note that for those familiar with using , that won't work here because we use a Docker environment to test sites. Supposedly there is a way to hack Docker compatibility into your usage of npm link, but it seems too complex relative to the solution here.)