@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. - 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.
import { downloadTemplate } from '@bluwy/giget-core'
const result = await downloadTemplate('unjs/template')
await downloadTemplate('unjs/template/subdir')
await downloadTemplate('unjs/template#main')
await downloadTemplate('gh:unjs/template')
await downloadTemplate('gitlab:unjs/template')
await downloadTemplate('bitbucket:unjs/template')
await downloadTemplate(
'https://api.github.com/repos/unjs/template/tarball/main',
)
await downloadTemplate('unjs/template', { dir: 'my-project' })
await downloadTemplate('unjs/template', { force: true })
await downloadTemplate('unjs/template', { force: 'clean' })
await downloadTemplate('unjs/template', { offline: true })
await downloadTemplate('unjs/template', { offline: 'prefer' })
await downloadTemplate('unjs/template', { provider: 'gitlab' })
await downloadTemplate('unjs/template', { providerOptions: { auth: 'xxx' } })
verifyTemplate
Check whether the template is valid. Requires network access.
import { verifyTemplate } from '@bluwy/giget-core'
await verifyTemplate('unjs/template')
await verifyTemplate('unjs/template/subdir')
await verifyTemplate('unjs/template#main')
await verifyTemplate('gh:unjs/template')
await verifyTemplate('gitlab:unjs/template')
await verifyTemplate('bitbucket:unjs/template')
await verifyTemplate('https://api.github.com/repos/unjs/template/tarball/main')
await verifyTemplate('unjs/non-existent-repo')
await verifyTemplate('unjs/template/not-existent-subdir')
await verifyTemplate('unjs/template#not-existent-branch')
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.
import { parseGitURI } from '@bluwy/giget-core'
parseGitURI('owner/repo')
parseGitURI('owner/repo/subdir')
parseGitURI('owner/repo#main')
parseGitURI('owner/repo/subdir#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. - Any
GIGET_
environment variables support are removed. They should be passed as explicit options instead.
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