Gatsby p5.js Starter

This is a ✏✏✏ WIP ✏✏✏ Gatsby starter that integrates with p5.js. View a live version of it at https://gatsby-p5-gallery-starter.herokuapp.com/.

I created it because I love working in p5.js and wanted a way to display my sketches, but I couldn't find any pre-existing scaffolding to do so in the Gatsby Starter Library. So I decided to create my own, so that others can easily show off their awesome sketches.

In this README, I've written detailed instructions on how to use this starter. If anything is not working for you, please create an issue, and I'll get right on it.

TODO

Add instructions on adding your own p5.js sketch
Refactor SketchWrapper using React Hooks API
Add tests that all gallery images have sketches and all sketches have gallery images

✨ Features

gatsby, obviously!
React integration for p5.js sketches. Note that this does not use react-p5-wrapper -- I've written my own wrapper for this starter.
responsive css-grid gallery with Sass

🚀 Getting Started

0. Make sure you have the basics.

Node.js In order to use this template, you need to have node.js installed. Run node -v on the command line, and if a version is displayed, you're good to go. If not, check out Gatsby's instructions on the appropriate installation for your machine.
Git You need Git in order to use Gatsby. If you don't have Git, get it using these instructions.
Gatsby CLI You'll need to install this node.js package globally, with sudo npm install -g gatsby-cli. Enter your password when prompted. Once it's finished installing, view the available commands by running gatsby --help.

NOTE! If you already have gatsby-cli, and you're seeing an error related to a missing dependency called ink, you need to update your gatsby-cli by running npm update gatsby. More information on this issue can be found here.

1. Create a Gatsby site.

Don't just clone this repo. Instead, use the Gatsby CLI to create a new site, specifying the starter project.

gatsby new <your-project-name> https://github.com/doubledherin/gatsby-p5-starter.git

This will create a new Gatsby project based on a clone of this repo.

2. 🔥 Fire it up!

cd into the new project directory that was created, then run

gatsby develop

Your site is now running at http://localhost:8000!

Note: You'll also see a second link: http://localhost:8000/___graphql. This is GraphiQL, a tool you can use to experiment with querying your data. Learn more about using this tool in the Gatsby tutorial.

Notice that you also have hot reloading out of the box: make an edit to src/pages/index.js. Save your changes and the browser will update in real time.

🔥 Hot reloading is hot hot hot. 🔥

3. Set up your Github repo.

Create a new repository on Github and then add it as the origin remote locally with

git remote add origin <url-of-your-github-repo>

Push your local master branch to the remote:

git push origin master

Add Your Own Content

How to Prepare a p5.js Sketch to be Added to Your Gallery

TL;DR

Copy this sketch template and paste it into src/scripts/sketches, making sure to name it exactly the same as the still image that will represent it in the gallery. (As you can see, all of the p5.js functions are namespaced with p. in this template so as not to dilute the global namespace.)
Copy your sketch's global variables into the "Initialize variables" section. The copy the body of your setup, draw and other p5.js built-in functions into the namespaced versions of them in the template (i.e. copy the body of your setup() function into p.setup()). If you are using a p5 function that isn't in the template, you can add it, just make sure to namespace it too.
If your editor has an eslint plugin, the linter should be hollering right about now about a bunch of undefined variables related to p5. For each one of this, add a p. namespace before it.
If you're using a p5 function or class that's already namespaced with p5, such as p5.Vector, uncomment this line in the template.

Once you've done all that you should be good to go. If you want to know why the heck you need to do this, read "The Deets," below.

The Deets

By default, all p5.js functions are in the global namespace (i.e. bound to the window object). This means you can run into conflicts with other libraries and other global variables.

To avoid trouble with this issue, I've set this starter up to rely on the "instance mode" of p5.js. In "instance mode", all p5 functions are bound up in a single variable which can be used as a namespace. Here is an example of this kind of sketch on the p5.js site. As you can see, the sketch template you need to use to add a new p5.js sketch to the gallery follows this same pattern. Then, the p5 instance is instantiated in this wrapper component.

For more information about instance mode, check out the p5.js docs on it, or even better, watch this.

The Gallery

How to Add a p5.js Work to the Gallery

Make sure to read the How to Prepare Your p5.js Sketch for This Site section before proceeding.

To add a p5.js work to the gallery, you need to add 2 things to your repo:

The still image for the Gallery page
The p5.js file itself (called a "sketch")

Both the image and the p5.js sketch need to have the same filename. For example, if the name of your sketch is "New World Order," the image should be called new-world-order.png and the sketch should be called new-world-order.js.

Place the image in the src/static/images/gallery/p5/ directory.

Place the sketch in the src/scripts/sketches directory.

The title of the artwork that displays when hovering on an item in the gallery is automatically derived from the image filename with this function.

How to Add a Still Image to the Gallery (for non-p5.js works)

The benefit of using this starter is that it's easy to add p5.js works to the gallery, but if you just want to add a still image, you can do that too -- just add the image to static/images/gallery and make sure not to put it in the /p5 subdirectory.

The Home Page

To change which p5.js sketch appears on the home page, change this import to point to the sketch file you want on the homepage.

The About Page

Replace this image with yours.

To move the image elsewhere on the page, put this line where you'd like the image to appear within the content.

The Content Page

Simply replace the static content found here.

Add or Remove Entire Pages

One of the nice things about Gatsby is that pages are generated automatically if they live in the pages/ directory. So to create a new page, simply add a new .jsx file to that directory.

To add the new page to the header navigation list, add a new Navlink item for it here.

To make sure the new header nav item animates nicely in mobile like the others, make sure it is accounted for here. Each nav item should have an &:nth-of-type(<n>) entry, and the transition-delay should be incremented by 0.1s for each successive item.

💫 Deployment

This starter has instructions on deployment to Heroku, but if you're interested in hosting your site somewhere else, there are plenty of options; check out the Gatsby docs.

If you don't already have a Heroku account, create one for free here.
Make sure you're logged in and go to your dashboard, at https://dashboard.heroku.com/apps.
In the top right corner, click "New", then "Create New App".
Enter a name for your app and choose a region. Ignore the 'Add to pipeline' option unless you need it (unlikely). Click "Create app".
If you don't have it already, download and install the Heroku CLI. If you're not sure, type heroku -v on the command line. If a version is printed to the terminal, you have the Heroku CLI. If not, you don't.
Once you have the Heroku CLI, you should be able to log in to Heroku on the command line. Do that by running heroku login
Add a heroku remote for your app: heroku git:remote -a <your-heroku-app-name>
Set the heroku/node.js and heroku-buildpack-static buildpacks on your application:

heroku buildpacks:set heroku/nodejs
heroku buildpacks:add https://github.com/heroku/heroku-buildpack-static.git

Heroku will automatically detect and run the build script from your package.json.

Heroku can only deploy from the master branch. Run git push heroku master to deploy what's on your local master branch; run git push heroku <local-branch-name>:master to deploy what's on your local branch.

Once it completes, your app should be deployed to your-app-name.herokuapp.com.

That should be all you need, but more information on deploying to Heroku can be found here.

Customizations

Typography

This starter uses Typography.js with the Bootstrap theme. To choose a different theme or to customize your own theme, follow these Typography.js docs or these Gatbsy-Typography ones.

Gallery Page

The images in the Gallery are automatically optimized for fluid responsive rendering using the gatsby-image, gatsby-plugin-sharp, and gatsby-transformer-sharp. They are dynamically rendered via GraphQL queries enabled by the gatsby-source-filesystem plugin.

Any image in src/static/images/gallery will appear on the Gallery page, and the text for the image is based on the filename. So if you want the text for your image to be "P5 Is Awesome", the filename of the image needs to be p5-is-awesome.<file extension>.

Clicking on any image in the gallery will redirect you to a page with a full-screen representation of the gallery item. The pages for each gallery item are generated dynamically in the gatsby-node.js config file. For more information on how this works, see the Gatsby tutorial of programatically creating pages.

🎓 Learning Gatsby

Looking for more guidance? Full documentation for Gatsby lives on the website. Here are some places to start:

For most developers, we recommend starting with our in-depth tutorial for creating a site with Gatsby. It starts with zero assumptions about your level of ability and walks through every step of the process.
To dive straight into code samples, head to our documentation. In particular, check out the Guides, API Reference, and Advanced Tutorials sections in the sidebar.

elykahn/gap5bye