π Easily fetch templates and Git repositories with joy!
π Support for popular Git providers (GitHub, GitLab, Bitbucket, Sourcehut) out of the box.
π Built-in and custom template registry.
π Fast cloning using tarball gzip without depending on local git and tar.
π» Works online and offline with disk cache support.
π€ Custom template provider support with programmatic usage.
π Support for extracting with a subdir.
π Authorization support to download private templates.
Enjoy exploring and trying out Gitize!
npx gitize@latest <template> [<dir>] [...options]
- π template: Template name or a URI describing provider, repository, subdir, and branch/ref. (See Examples)
- π dir: A relative or absolute path where to extract the template.
--force
: Clone to existing directory even if exists.--offline
: Do not attempt to download and use cached version.--prefer-offline
: Use cache if exists otherwise try to download.--force-clean
: π₯ Remove any existing directory or file recursively before cloning.--shell
: π Open a new shell with current working directory in cloned dir. (Experimental).--registry
: URL to a custom registry. (Can be overridden withGITIZE_REGISTRY
environment variable).--no-registry
: Disable registry lookup and functionality.--verbose
: Show verbose debugging info.--cwd
: Set current working directory to resolve dirs relative to it.--auth
: Custom Authorization token to use for downloading template. (Can be overridden withGITIZE_AUTH
environment variable).
# Clone nuxt starter from gitize template registry
npx gitize@latest nuxt
# Clone the main branch of github.com/unjs/template to unjs-template directory
npx gitize@latest gh:unjs/template
# Clone to myProject directory
npx gitize@latest gh:unjs/template myProject
# Clone dev branch
npx gitize@latest gh:unjs/template#dev
# Clone /test directory from main branch
npx gitize@latest gh:unjs/template/test
# Clone from gitlab
npx gitize@latest gitlab:unjs/template
# Clone from bitbucket
npx gitize@latest bitbucket:unjs/template
# Clone from sourcehut
npx gitize@latest sourcehut:pi0/unjs-template
Gitize has a built-in HTTP registry system for resolving templates. This way you can support template name shortcuts and meta-data. Default registry is served from nyxlabs/gitize/templates.
If you want to add your template to the built-in registry, just drop a PR to add it to the ./templates directory. Slugs are added on first-come first-served basis but this might change in the future.
Creating a custom registry is like weaving a magical spell - it lets you take control of your templates and unleash their full potential. Your custom registry should provide an endpoint with a dynamic path /:template.json
that returns a JSON response with keys same as custom providers.
- π
name
: (required) Name of the template. - π¦
tar
(required) Link to the tar download link. - π
defaultDir
: (optional) Default cloning directory. - π
url
: (optional) Webpage of the template. - π
subdir
: (optional) Directory inside the tar file. - π
headers
: (optional) Custom headers to send while downloading template.
Because of the simplicity, you can even use a GitHub repository as template registry. But, with a custom registry, you can build something even more powerful by bringing your own API. So, let your magic flow and create your own custom registry with Gitize!
Install:
#nyxi
nyxi gitize
# pnpm
pnpm install gitize
# npm
npm install gitize
# yarn
yarn install gitize
π₯ Import:
// ESM
import { downloadTemplate } from 'gitize'
// CommonJS
const { downloadTemplate } = require('gitize')
π‘ Example::
const { source, dir } = await downloadTemplate('github:nyxlabs/template')
βοΈ Options:
source
: (string) Input source in the format of[provider]:repo[/subpath][#ref]
.options
: (object) Options are usually inferred from the input string. You can customize them.- π
dir
: (string) Destination directory to clone to. If not provided,user-name
will be used relative to the current directory. - π€
provider
: (string) Eithergithub
,gitlab
,bitbucket
orsourcehut
. The default isgithub
. - π¦
repo
: (string) Name of the repository in the format of{username}/{reponame}
. - π
ref
: (string) Git ref (branch or commit or tag). The default value ismain
. - π
subdir
: (string) Directory of the repo to clone from. The default value is none. - π₯
force
: (boolean) Extract to the existing directory even if it already exists. - π§Ή
forceClean
: (boolean)β οΈ Clean up any existing directory or file before cloning. - π
offline
: (boolean) Do not attempt to download and use a cached version. - πΎ
preferOffline
: (boolean) Use the cache if it exists; otherwise, try to download. - πΊοΈ
providers
: (object) A map from provider name to custom providers. Can be used to override built-ins too. - π
registry
: (string or false) Set tofalse
to disable the registry. Set to a URL string (without a trailing slash) for a custom registry. (Can be overridden withGITIZE_REGISTRY
environment variable). - ποΈ
cwd
: (string) Current working directory to resolve directories relative to it. - π
auth
: (string) Custom authorization token to use for downloading the template. (Can be overridden withGITIZE_AUTH
environment variable).
- π
π Return value:
The return value is a promise that resolves to the resolved template.
- π
dir
: (string) Path to the extracted directory. - π
source
: (string) Normalized version of the input source without the provider. - [other provider template keys]
- π
url
: (string) URL of the repository that can be opened in a browser. Useful for logging.
- π
With Gitize's programmatic method, you can create your own custom template providers and unlock a world of possibilities!
import type { TemplateProvider } from 'gitize'
const rainbow: TemplateProvider = async (input, { auth }) => {
return {
name: 'rainbow',
version: input,
headers: { authorization: auth },
url: `https://rainbow.template/?variant=${input}`,
tar: `https://rainbow.template/dl/rainbow.${input}.tar.gz`,
}
}
const { source, dir } = await downloadRepo('rainbow:one', {
providers: { rainbow },
})
You can define additional custom registry providers using the registryProvider
utility and register them with providers
. With this feature, you can further customize your Gitize experience and make it work for you!
import { registryProvider } from 'gitize'
const themes = registryProvider(
'https://raw.githubusercontent.com/nyxlabs/gitize/main/templates'
)
const { source, dir } = await downloadRepo('themes:test', {
providers: { themes },
})
- π Clone this repository
- π Enable Corepack using
corepack enable
(usenpm i -g corepack
for Node.js < 16.10) - π¦ Install dependencies using
nyxi
- π§ͺ Run interactive tests using
nyxr dev
MIT Made with π