lukekarrys/universal-static-instagram lukekarrys/universal-static-instagram

A universal JS static site generator for Instagram built with React. Demo:

Host: GitHub

Language: JavaScript

Keywords: instagram, fetch, static


Build Status


  1. Fetch Instagram data
  2. Build HTML and Universal JavaScript
  3. Deploy static files

Instagram API Updates (as of June 1, 2016)

Instagram API updates went into effect on June 1, 2016. According to the new terms, API clients are in Sandbox mode by default and will only be allowed to download data for the user who created the app (and up to 9 other accounts which must first approve the application request) and the last 20 posts for each user.

What is this?


Way back when, Instagram was iOS only and didn't have a web interface. I wanted one so I built some tools that would download the JSON and images and would publish them as a static site. This site idly for the most part while Instagram created amazing interfaces on all platforms.

Then I deleted my account. Before I deleted it I downloaded all the images and JSON from the API with the plan of using this to just display them on the web. It had no CSS and no (useful) JS, but it kinda worked. But the fact that it was Ruby and Jekyll, which are two things I don't use much anymore, meant it sat untouched.

So I decided to rewrite it using react, react-router, redux, and webpack to be a static site (same as before) but so react and react-router can take over the clientside (and now I'll hopefully do cooler stuff with it).


  • Output static .html files for every page
  • Output static .json files for each "API route"
  • Completely usable with JS disabled
  • react + react-router takeover client-side on load
  • Can be self hosted, including images
  • Easy to fetch latest or refresh existing Instagram data/media
  • Easy deployment to any static hosting including Surge or GitHub Pages


The best way to use this is by forking and cloning the repo. After that you'll want to run the initial setup commands.

Initial Setup

  • cd into the root of the repo
  • npm install
  • npm run make.config
  • npm run (this could take a few minutes)

Now you should have a config.json file with the information you entered and a _cache/USER_ID directory with all your Instagram data. These are both ignored by default and shouldn't be checked into the repo (especially the config.json which has your access token).

Next you can either edit some of the src files to change the appearance and layout of your site, or just go straight to deploying it to your favorite static hosting.


All the files for the client are located in the src/ directory. Check out the Client Architecture docs for an explanation of the organization and how to go about changing certain things. As you edit things you'll want to see these changes live in your browser, so you'll need to run:

npm start

This spins up a webpack-dev-server with react-hot-loader and you should be able to see that site at http://localhost:3000.

Note: changes inside the src/ directory should hot load in your browser, but any changes to the webpack.config.js or the server/ directory will require the dev server to be restarted. Also if you rerun npm run you'll need to restart the dev server as well.


Whether you made some local modifications or not, the next step is to build all the static files for the site. As stated in the goals section above, this project aims to create an html file for each page, json file for each set of data, and a jpg for each image size. This can mean a lot of files!

My local example has 3572 files and directories for ~500 Instagram posts. This may seem like a lot (and some of it is technically duplicated between json and html), but storage is cheap. The benefits are that each page can be loaded on its own (without JS) and look exactly as it would if it were loaded clientside by populating our redux store with the plain json.

This may seem like overkill (it probably is), but hey, it's one of the goals of the project. You can't argue with goals! To do this:

npm run build

Note: This will also minify the JS bundle with a hashed filename like bundle.HASH.js and do some other webpack stuff to get it ready for production.


Now you have a directory of static files. It includes a 404.html to serve when the requested path doesn't exist and a CNAME file with your domain (if selected). The only requirement to serve this is a basic web server that can serve .html, .js, .css, .json, and .jpg files appropriately. There are also a few built in options since they require so little setup.


npm run deploy.surge

Surge is really great. If you don't have an account, running this command will prompt you to create one and then it will deploy your site to the domain you chose when running npm run make.config (via a CNAME file). If you didn't pick a domain, Surge will prompt you for one. See the Surge help docs for more information.

Note: currently Surge uploads every file for each deployment. This means that even if you only make one small style tweak, the deploy process will still have to upload all the files and images which could be 100s of megabytes. There is an open issue on the project to allow deploying based on diffs only, but it hasn't been implemented. If this is an issue for you, I recommend using GitHub Pages for deploying.

GitHub Pages

npm run
# Or deploy to a different repository
npm run -- --repo [email protected]:lukekarrys/

Since you already have this forked on GitHub, and every path has a matching built file, you can use GitHub Pages, which is pretty neat. Running the above command will push the built site up to your GitHub fork on the gh-pages branch. If you picked a domain when running npm run make.config it will create a CNAME file for you. See the GitHub Pages help docs for more information.

You can also deploy to a different repository by using cli argument: --repo [email protected]:USERNAME/REPO_NAME.git. This uses git-directory-deploy under the hood, so check out the other available arguments in the documentation.

Re-fetching Data

Running npm run again will start after the most recent Instagram post ID, so that you can easily only fetch the latest Instagram data. Sometimes you'll want to refresh all the existing Instagram json data as well.

npm run -- --refresh

Also, by default Instagram only includes a few likes and comments with each post. You have the option (at the expense of two extra API requests per post) to fetch as many likes and comments as Instagram allows (which right now is ~120 each).

npm run -- --full

These commands can be combined as well:

npm run -- --refresh --full

Note: Instagram photos are never redownloaded because they should never change after being posted.


PRs, issues, and feature requests welcome!

If you are submitting a PR, make sure that npm run lint passes after you've written your code.




Kind Requirements Latest Stable Latest Release Licenses
clipboard runtime ~> 1.0.1 1.1.1 1.1.1 MIT
hashie runtime ~> 1.2.0 3.5.5 3.5.5 MIT
highline runtime ~> 1.6.15 1.7.8 2.0.0.pre.develop.6 Ruby
htmlentities runtime ~> 4.3.1 4.3.4 4.3.4 MIT
httpclient runtime ~> 2.3.1 2.8.3 2.8.3 Ruby
instagram runtime ~> 0.8.5 1.1.6 1.1.6 BSD-3-Clause
jekyll runtime ~> 0.12 3.4.3 3.4.3 MIT
rake runtime ~> 10.0.2 12.0.0 12.0.0 MIT
rdiscount runtime ~> 1.6.8 2.2.0 BSD-3-Clause
stringex runtime ~> 1.5.1 2.7.1 2.7.1 MIT
Kind Requirements Latest Stable Latest Release Licenses
@lukekarrys/eslint-config development ^2.1.6 2.1.11 2.1.11 MIT
async development ^2.0.1 2.2.0 2.2.0 MIT
autoprefixer development ^6.4.0 6.7.7 6.7.7 MIT
babel development ^6.5.2 6.23.0 6.23.0 MIT
babel-cli development ^6.11.4 6.24.0 7.0.0-alpha.6 MIT
babel-core development ^6.13.2 6.24.0 7.0.0-alpha.6 MIT
babel-eslint development ^7.0.0 7.2.1 7.2.1 MIT
babel-loader development ^6.2.4 6.4.1 7.0.0-beta.1 MIT
babel-plugin-add-module-exp... development ^0.2.1 0.2.1 0.2.1 MIT
babel-plugin-lodash development ^3.2.6 3.2.11 3.2.11 MIT
babel-plugin-transform-deco... development ^1.3.4 1.3.4 1.3.4 MIT
babel-plugin-transform-reac... development ^6.9.1 6.23.0 7.0.0-alpha.3 MIT
babel-plugin-transform-reac... development ^6.8.0 6.22.0 7.0.0-alpha.3 MIT
babel-plugin-transform-reac... development ^0.2.9 0.3.2 0.3.2 MIT
babel-plugin-transform-runtime development ^6.12.0 6.23.0 7.0.0-alpha.3 MIT
babel-preset-es2015 development ^6.13.2 6.24.0 7.0.0-alpha.3 MIT
babel-preset-react development ^6.11.1 6.23.0 7.0.0-alpha.1 MIT
babel-preset-react-hmre development ^1.1.1 1.1.1 1.1.1 ISC
babel-preset-stage-0 development ^6.5.0 6.22.0 6.22.0 MIT
babel-register development ^6.11.6 6.24.0 7.0.0-alpha.2 MIT
babel-runtime development ^6.11.6 6.23.0 7.0.0-alpha.1 MIT
colors development ^1.1.2 1.1.2 1.1.2 MIT
common-tags development ^1.3.1 1.4.0 1.4.0 MIT
cpr development ^2.0.0 2.0.2 2.0.2 BSD-3-Clause
css-loader development ^0.25.0 0.27.3 0.27.3 MIT
css-modules-require-hook development ^4.0.1 4.0.6 4.1.0-beta MIT
cssnano development ^3.7.3 3.10.0 3.10.0 MIT
dateformat runtime ^1.0.12 2.0.0 2.0.0 MIT
debug development ^2.2.0 2.6.3 2.6.3 MIT
eslint development ^3.2.2 3.18.0 3.18.0 MIT
eslint-import-resolver-webpack development ^0.6.0 0.8.1 0.8.1 MIT
eslint-plugin-classes development ^0.1.1 0.1.1 0.1.1 MIT
eslint-plugin-import development ^2.0.0 2.2.0 2.2.0 MIT
eslint-plugin-react development ^6.4.1 6.10.2 6.10.2 MIT
git-directory-deploy development ^1.5.1 1.5.1 1.5.1 MIT
git-validate development ^2.1.4 2.2.2 2.2.2 MIT
hjs-webpack development ^8.3.0 9.0.0 9.0.0 MIT
html-tagged-literals development ^1.0.2 1.0.2 1.0.2 MIT
http-server development ^0.9.0 0.9.0 0.9.0 MIT
humps development ^2.0.0 2.0.0 2.0.0 MIT
inquirer development ^1.1.2 3.0.6 3.0.6 MIT
instagram-download development ^2.2.4 2.2.5 2.2.5 MIT
instagram-node development ^0.5.8 0.5.8 0.5.8 MIT
lodash runtime ^4.14.2 4.17.4 4.17.4 MIT
minimist development ^1.2.0 1.2.0 1.2.0 MIT
normalizr runtime ^2.2.1 3.2.2 3.2.2 MIT
on-build-webpack development ^0.1.0 0.1.0 0.1.0 MIT
postcss-loader development ^1.0.0 1.3.3 1.3.3 MIT
react runtime ^15.3.0 15.4.2 16.0.0-alpha.6 BSD-3-Clause
react-dom runtime ^15.3.0 15.4.2 16.0.0-alpha.6 BSD-3-Clause
react-redux runtime ^4.4.5 5.0.3 5.0.3 MIT
react-router runtime ^3.0.0 4.0.0 4.0.0 MIT
react-router-redux runtime ^4.0.5 4.0.8 5.0.0-alpha.4 MIT
rebass runtime ^0.1.5 0.3.4 0.4.0-beta.9 MIT
redux runtime ^3.5.2 3.6.0 3.6.0 MIT
redux-devtools development ^3.3.1 3.3.2 3.3.2 MIT
redux-devtools-dock-monitor development ^1.1.1 1.1.1 1.1.1 MIT
redux-logger runtime ^2.6.1 3.0.0 3.0.0 MIT
redux-slider-monitor development ^1.0.7 1.0.7 1.0.7 MIT
redux-thunk runtime ^2.1.0 2.2.0 2.2.0 MIT
rimraf development ^2.5.4 2.6.1 2.6.1 ISC
style-loader development ^0.13.1 0.16.1 0.16.1 MIT
surge development ^0.18.0 0.19.0 0.19.0 ISC
webpack development ^1.13.1 2.3.2 2.3.2 MIT
xhr runtime ^2.2.2 2.4.0 2.4.0 MIT
zero-fill runtime ^2.2.3 2.2.3 2.2.3 MIT

Project Statistics

Sourcerank 5
Size 52.5 MB
Stars 40
Forks 9
Watchers 2
Open issues 3
Dependencies 76
Contributors 3
Tags 0
Last updated
Last pushed

Top Contributors See all

Luke Karrys Greenkeeper Richard

Something wrong with this page? Make a suggestion

Last synced: 2016-10-26 04:19:10 UTC