@bluwy/giget-core

A JavaScript API to download a template from a git repository or URL. The code is largely based on giget (and includes its license), but with the below main differences:

• Only the JavaScript API. The CLI and unrelated APIs are stripped off.
• Reduced dependencies to only 1 (tar).
• Modified API interface (reduce input and output surface).
• Removed custom registries and JSON template support.
• Removed GIGET_ special environment variables support.
• Removed fetch proxy support (awaiting builtin solution).
• Supports fetching the default branch of a repository.
• Additional API utilities.
• Node >=18 and ESM only.

Usage

The API is heavily documented in ./src/index.d.ts. Below shows some examples of using them:

downloadTemplate

Download a template with a given input string.

1import { downloadTemplate } from '@bluwy/giget-core'
2
3// Basic usage. Download from github repo.
4const result = await downloadTemplate('unjs/template')
5// info: { ... } - The template information parsed by providers
6// dir: '...' - The directory where the template is downloaded to
7// source: '...' - The source URL of the template (Prefix like `gh:` is stripped)
8
9// Other input syntaxes
10await downloadTemplate('unjs/template/subdir')
11await downloadTemplate('unjs/template#main')
12await downloadTemplate('gh:unjs/template')
13await downloadTemplate('gitlab:unjs/template')
14await downloadTemplate('bitbucket:unjs/template')
15await downloadTemplate(
16  'https://api.github.com/repos/unjs/template/tarball/main',
17)
18
19// Download to a specific directory (relative to cwd)
20await downloadTemplate('unjs/template', { dir: 'my-project' })
21
22// Download to a directory even if it has existing content
23// (merges directories and replaces matching files)
24await downloadTemplate('unjs/template', { force: true })
25
26// Clean directory before downloading to it
27await downloadTemplate('unjs/template', { force: 'clean' })
28
29// Use offline cache only
30await downloadTemplate('unjs/template', { offline: true })
31
32// Use offline cache if available, otherwise download
33await downloadTemplate('unjs/template', { offline: 'prefer' })
34
35// Specify provider explicitly (if input has a provider prefix, it'll
36// take precedence instead)
37await downloadTemplate('unjs/template', { provider: 'gitlab' })
38
39// Pass authentication token to access private repositories
40// (handled by providers to pass as headers when downloading the tarball)
41await downloadTemplate('unjs/template', { providerOptions: { auth: 'xxx' } })

verifyTemplate

Check whether the template is valid. Requires network access.

1import { verifyTemplate } from '@bluwy/giget-core'
2
3await verifyTemplate('unjs/template') // true
4await verifyTemplate('unjs/template/subdir') // true
5await verifyTemplate('unjs/template#main') // true
6await verifyTemplate('gh:unjs/template') // true
7await verifyTemplate('gitlab:unjs/template') // true
8await verifyTemplate('bitbucket:unjs/template') // true
9await verifyTemplate('https://api.github.com/repos/unjs/template/tarball/main') // true
10
11await verifyTemplate('unjs/non-existent-repo') // false
12await verifyTemplate('unjs/template/not-existent-subdir') // false
13await verifyTemplate('unjs/template#not-existent-branch') // false

parseGitURI

Parse an input (e.g. 'owner/repo/templates/foo#main') into a GitInfo object. Useful for custom providers that need to parse the given input.

1import { parseGitURI } from '@bluwy/giget-core'
2
3parseGitURI('owner/repo') // { repo: 'owner/repo', subdir: '/' }
4parseGitURI('owner/repo/subdir') // { repo: 'owner/repo', subdir: '/subdir' }
5parseGitURI('owner/repo#main') // { repo: 'owner/repo', subdir: '/', ref: 'main' }
6parseGitURI('owner/repo/subdir#main') // { repo: 'owner/repo', subdir: '/subdir', ref: 'main' }

Migrate from giget

giget exports a downloadTemplate programmatic API as well. For most basic usecases, there's no significant difference and should be a drop-in replacement. However, there's certain features that work differently:

• The forceClean option is merged as force: 'clean'.
• The preferOffline option is merged as offline: 'prefer'.
• The registry option is removed. You can no longer download templates hosted from giget. Pass the direct tarball URL or git repo instead.
• The install and silent options used for installing dependencies is removed. You should manually install the dependencies yourself. Previously giget used nypm under the hood.
• The auth option is moved to providerOptions.auth.
• The TemplateProvider and TemplateInfo interfaces used by the providers option is slightly changed.
  • TemplateProvider: The function must return a TemplateInfo instead of null. If it fails to handle something, it should try a helpful error.
  • TemplateInfo: It no longer allows returning arbitrary keys in the object.
• The returned object has the TemplateInfo on the info property instead of spreading on the returned object.
• GIGET_ environment variables support is removed. They should be passed as explicit options instead.
• Fetch proxy support is removed (awaiting builtin solution).

Attribution

As mentioned above, this project is based heavily on giget! Thanks @pi0 for the original work and battle-testing it.

In the future, I hope the code here can be merged back to giget, perhaps as a giget-core library, and have the giget CLI as a wrapper library.

License

MIT