Package Exports
- @octokit/core
This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@octokit/core) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.
Readme
core.js
Extendable client for GitHub's REST & GraphQL APIs
If you need a minimalistic library to utilize GitHub's REST API and GraphQL API which you can extend with plugins as needed, than @octokit/core is a great starting point.
If you don't need the Plugin API then using @octokit/request or @octokit/graphql directly is a good alternative.
Usage
| Browsers |
Load @octokit/core directly from cdn.pika.dev
<script type="module">
import { Octokit } from "https://cdn.pika.dev/@octokit/core";
</script> |
|---|---|
| Node |
Install with const { Octokit } = require("@octokit/core");
// or: import { Octokit } from "@octokit/core"; |
REST API example
// Create a personal access token at https://github.com/settings/tokens/new?scopes=repo
const octokit = new Octokit({ auth: `personal-access-token123` });
const response = await octokit.request("GET /orgs/:org/repos", {
org: "octokit",
type: "private"
});See @octokit/request for full documentation of the .request method.
GraphQL example
const octokit = new Octokit({ auth: `secret123` });
const response = await octokit.graphql(
`query ($login: String!) {
organization(login: $login) {
repositories(privacy: PRIVATE) {
totalCount
}
}
}`,
{ login: "octokit" }
);See (@octokit/graphql](https://github.com/octokit/graphql.js) for full documentation of the .graphql method.
Options
| name | type | description |
|---|---|---|
options.auth
|
String or @octokit/auth instance
|
If set to a String, then it's expected to be a personal access token or OAuth access token and used accordingly in the Authorization header.For all other authentication strategies, set options.auth to a @octokit/auth instance.See Authentication below for examples. |
options.baseUrl
|
String
|
When using with GitHub Enterprise Server, set const octokit = new Octokit({
baseUrl: "https://github.acme-inc.com/api/v3"
}); |
options.previews
|
Array of Strings
|
Some REST API endpoints require preview headers to be set, or enable additional features. Preview headers can be set on a per-request basis, e.g. octokit.request("POST /repos/:owner/:repo/pulls", {
mediaType: {
previews: ["shadow-cat"]
},
owner,
repo,
title: "My pull request",
base: "master",
head: "my-feature",
draft: true
});You can also set previews globally, by setting the const octokit = new Octokit({
previews: ["shadow-cat"]
}); |
options.request
|
Object
|
Set a default request timeout ( There are more |
options.userAgent
|
String
|
A custom user agent string for your app or library. Example const octokit = new Octokit({
userAgent: "my-app/v1.2.3"
}); |
Defaults
You can create a new Octokit class with customized default options.
const MyOctokit = Octokit.defaults({
auth: "personal-access-token123",
baseUrl: "https://github.acme-inc.com/api/v3",
userAgent: "my-app/v1.2.3"
});
const octokit1 = new MyOctokit();
const octokit2 = new MyOctokit();Authentication
You can set options.auth to a token, which will be used to correctly set the Authorization header for the requests you do with octokit.request() and octokit.graphql(). Example
import { Octokit } from "@octokit/core";
const octokit = new Octokit({
auth: "mypersonalaccesstoken123"
});
octokit.request("/user").then(response => console.log(response.data));All other authentication strategies are supported using @octokit/auth, just pass the auth() method returned by any of the strategies as options.auth. Example
import { Octokit } from "@octokit/core";
import { createAppAuth } from "@octokit/auth-app";
const octokit = new Octokit({
auth: createAppAuth({
id: 123,
privateKey: process.env.PRIVATE_KEY
)}
})
octokit.request('/app').then(response => console.log(response.data))Hooks
You can customize Octokit's request lifecycle with hooks.
octokit.hook.before("request", async options => {
validate(options);
});
octokit.hook.after("request", async (response, options) => {
console.log(`${options.method} ${options.url}: ${response.status}`);
});
octokit.hook.error("request", async (error, options) => {
if (error.status === 304) {
return findInCache(error.headers.etag);
}
throw error;
});
octokit.hook.wrap("request", async (request, options) => {
// add logic before, after, catch errors or replace the request altogether
return request(options);
});See before-after-hook for more documentation on hooks.
Plugins
Octokit’s functionality can be extended using plugins. THe Octokit.plugin() method accepts a function or an array of functions and returns a new constructor.
A plugin is a function which gets two arguments:
- the current instance
- the Options passed to the constructor.
// index.js
const MyOctokit = require("@octokit/core").plugin([
require("./lib/my-plugin"),
require("octokit-plugin-example")
]);
const octokit = new MyOctokit({ greeting: "Moin moin" });
octokit.helloWorld(); // logs "Moin moin, world!"
octokit.request("GET /"); // logs "GET / - 200 in 123ms"
// lib/my-plugin.js
module.exports = (octokit, options = { greeting: "Hello" }) => {
// add a custom method
octokit.helloWorld = () => console.log(`${options.greeting}, world!`);
// hook into the request lifecycle
octokit.hook.wrap("request", async (request, options) => {
const time = Date.now();
const response = await request(options);
console.log(
`${options.method} ${options.url} – ${response.status} in ${Date.now() -
time}ms`
);
return response;
});
};