@bluwy/giget-core
v0.1.1
Published
Download template from a git repo or tarball URL
Downloads
33,891
Maintainers
Readme
@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. - 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'
// Basic usage. Download from github repo.
const result = await downloadTemplate('unjs/template')
// info: { ... } - The template information parsed by providers
// dir: '...' - The directory where the template is downloaded to
// source: '...' - The source URL of the template (Prefix like `gh:` is stripped)
// Other input syntaxes
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',
)
// Download to a specific directory (relative to cwd)
await downloadTemplate('unjs/template', { dir: 'my-project' })
// Download to a directory even if it has existing content
// (merges directories and replaces matching files)
await downloadTemplate('unjs/template', { force: true })
// Clean directory before downloading to it
await downloadTemplate('unjs/template', { force: 'clean' })
// Use offline cache only
await downloadTemplate('unjs/template', { offline: true })
// Use offline cache if available, otherwise download
await downloadTemplate('unjs/template', { offline: 'prefer' })
// Specify provider explicitly (if input has a provider prefix, it'll
// take precedence instead)
await downloadTemplate('unjs/template', { provider: 'gitlab' })
// Pass authentication token to access private repositories
// (handled by providers to pass as headers when downloading the tarball)
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') // true
await verifyTemplate('unjs/template/subdir') // true
await verifyTemplate('unjs/template#main') // true
await verifyTemplate('gh:unjs/template') // true
await verifyTemplate('gitlab:unjs/template') // true
await verifyTemplate('bitbucket:unjs/template') // true
await verifyTemplate('https://api.github.com/repos/unjs/template/tarball/main') // true
await verifyTemplate('unjs/non-existent-repo') // false
await verifyTemplate('unjs/template/not-existent-subdir') // false
await 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.
import { parseGitURI } from '@bluwy/giget-core'
parseGitURI('owner/repo') // { repo: 'owner/repo', subdir: '/' }
parseGitURI('owner/repo/subdir') // { repo: 'owner/repo', subdir: '/subdir' }
parseGitURI('owner/repo#main') // { repo: 'owner/repo', subdir: '/', ref: 'main' }
parseGitURI('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 asforce: 'clean'
. - The
preferOffline
option is merged asoffline: '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
andsilent
options used for installing dependencies is removed. You should manually install the dependencies yourself. Previouslygiget
used nypm under the hood. - The
auth
option is moved toproviderOptions.auth
. - The
TemplateProvider
andTemplateInfo
interfaces used by theproviders
option is slightly changed.TemplateProvider
: The function must return aTemplateInfo
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.
- Debug logs are removed. (Perhaps to revisit if they're helpful in the future)
- The returned object has the
TemplateInfo
on theinfo
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