11

I was browsing the next.js repository and noticed this function that downloads and extracts a template from GitHub, with tar:

export async function downloadAndExtractExample(
  root: string,
  name: string
): Promise<void> {
  return await promisePipe(
    got.stream('https://codeload.github.com/zeit/next.js/tar.gz/canary'),
    tar.extract({ cwd: root, strip: 3 }, [`next.js-canary/examples/${name}`])
  )
}

I searched on StackOverflow and I only found this:

That's a thread explaining how you can pull a tar.gz from GitHub, but there is no mention of the "codeload" subdomain. How is it different to "api"?

Paul Razvan Berg
  • 16,949
  • 9
  • 76
  • 114

1 Answers1

13

The GitHub API provides the best way to get a URL to download an archive. When you make a GET request on that URL, it will redirect you to a URL on codeload.github.com. codeload is the service which provides archives for download and it's on its own domain for caching reasons.

While it's possible to use the codeload URL directly, you generally want to use the API URL, since it handles things like authentication more gracefully, and the codeload URLs for private repositories are generally ephemeral.

bk2204
  • 64,793
  • 6
  • 84
  • 100
  • 1
    Interesting. Perhaps Next.js decided to not use the API to avoid having to handle the redirect. Do you know whether `codeload.github.com` is going to be maintained? – Paul Razvan Berg Oct 17 '20 at 20:23
  • 1
    I don't know of any plans to remove it or stop supporting it, but I very strongly suggest using the API. There may be certain edge cases with ref names or other behaviors which are handled differently by `codeload.github.com` URLs that the API will handle gracefully. – bk2204 Oct 17 '20 at 21:14
  • Sure, but there are cases where I need to use Codeload instead of the API. I'm building a [CLI tool](https://github.com/paulrberg/create-eth-app) and the code is supposed to run on other people's computers only once, to bootstrap a boilerplate. Asking users to first authenticate with a GitHub token would be impractical. Thus I'm using Codeload because of it provides the exact service I need: archives for downloads. – Paul Razvan Berg Nov 11 '20 at 22:44
  • You can use an unauthenticated REST API request, no token needed. Not using a token will subject to you to lower rate limits, but it will still work. – bk2204 Nov 11 '20 at 22:56