GitHub Gist REST API Wrapper
A simple promise-based wrapper over the GitHub's REST API to play with GitHub Gists.
Installation
npm install @vighnesh153/github-gist
# Peer dependency
npm install axios
Before you begin
To interact with the gist in your GitHub account, you need to create a Personal Access Token with the gist scope.
- Generate your token
- Create a GitHub Gist by visiting this link. You might have to create a dummy file because
GitHub doesn't allow you to create empty gist. Once you have created the gist, note down the gist id (found in the
url)
- CORS configuration (if you are using this on a browser): The
GET
API to fetch the content of a file in a gist, is
CORS protected. If you are using this library on a browser, then you will get CORS blocked. To prevent that, I have
added a default CORS proxy server configuration https://corsanywhere.herokuapp.com/
. But, it is not a good idea to
use this default in production because it probably isn't reliable. The owner might decide to shut it down anytime. So,
I recommend you to build/host your own proxy or opt in for a more reliable one. Following are some helpful links (I
found these options via a quick google search and these are just to get you started and not my recommendations):
- A cheap paid service option: https://cors.sh/
- Host one of the following proxy server code on your platform of choice
- Create your own CORS proxy from scratch
Usage
Importing
import { GithubGist } from '@vighnesh153/github-gist';
const { GithubGist } = require('@vighnesh153/github-gist');
- As a script tag (UMD modules)
<script src="https://cdn.jsdelivr.net/npm/@vighnesh153/github-gist/dist/main.umd.js"></script>
<script>
const GithubGist = GithubGistUmd.GithubGist;
</script>
Instantiation
const gist = await GithubGist.initializeUsingGistId({
personalAccessToken: '<GITHUB_PERSONAL_ACCESS_TOKEN>',
gistId: '<YOUR-GIST-ID>',
enableRequestCaching: true,
isPublic: false,
corsConfig: { type: 'default' },
});
Files in Gist
A gist can have multiple files. To create a file, do the following:
You can only store string
content in a file. So, if you are creating a JSON file, remember to stringify the content
const pikachuJson = gist.createNewFile('pikachu.json');
console.log(pikachuJson.content);
pikachuJson.content = JSON.stringify({ message: 'Pikachu is the best' });
console.log(JSON.parse(pikachuJson.content));
Save a file
Just creating the file won't save it on your GitHub Gist. To save, you will have to invoke the save()
method on it
await pikachuJson.save();
Save multiple files at once
If you have multiple new files or modified files, you can invoke save()
on the gist itself to save all the files in a
single HTTP request
const pikachuPython = gist.createNewFile('pikachu.py');
pikachuPython.content = `print("Pikachu is the best")`;
const pikachuJs = gist.createNewFile('pikachu.js');
pikachuJs.content = `console.log("Pikachu is the best")`;
await gist.save();
Get an existing file
You can access the previously created file by doing the following
const existingPikachuJson = gist.getFileByName('pikachu.json');
Alternatively, you can also use createNewFile
which will return the existing file, if it exists, else, create it and
return it.
const existingPikachuJson = gist.createNewFile('pikachu.json');
Fetch the latest content of a gist
If you suspect that your local gist instance is out of date with the actual GitHub Gist, you can fetch the latest
content
await gist.fetchLatestContent();
await pikachuJson.fetchLatestContent();
Get all the files
const files = gist.files;
Get the owner of the gist
const ownerLogin = gist.owner;
Things to be aware of
Gist is an awesome way to store small amount data without having to spin up a database. But it does come with some
caveats.
- You cannot use it in a multi-threaded application because all the
save
requests are force
pushes, and you could
overwrite other thread's changes - Requests are not atomic
- Don't invoke
save
in parallel. Wait for the previous Promise
to resolve completely before starting the next one.