Home

Awesome

giget

npm version npm downloads Codecov

Download templates and git repositories with pleasure!

Features

✨ Support 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 extracting with a sub dir.

✨ Authorization support to download private templates

✨ Optionally install dependencies after clone using unjs/nypm

✨ HTTP proxy support and native fetch via unjs/node-fetch-native

Usage (CLI)

npx giget@latest <template> [<dir>] [...options]

Arguments

Options

Examples

# Clone nuxt starter from giget template registry
npx giget@latest nuxt

# Clone the main branch of github.com/unjs/template to unjs-template directory
npx giget@latest gh:unjs/template

# Clone to myProject directory
npx giget@latest gh:unjs/template myProject

# Clone dev branch
npx giget@latest gh:unjs/template#dev

# Clone /test directory from main branch
npx giget@latest gh:unjs/template/test

# Clone from gitlab
npx giget@latest gitlab:unjs/template

# Clone from bitbucket
npx giget@latest bitbucket:unjs/template

# Clone from sourcehut
npx giget@latest sourcehut:pi0/unjs-template

# Clone from https URL (tarball)
npx giget@latest https://api.github.com/repos/unjs/template/tarball/main

# Clone from https URL (JSON)
npx giget@latest https://raw.githubusercontent.com/unjs/giget/main/templates/unjs.json

Template Registry

Giget has a built-in HTTP registry system for resolving templates. This way you can support template name shortcuts and meta-data. The default registry is served from unjs/giget/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 a first-come first-served basis but this might change in the future.

Custom Registry

A custom registry should provide an endpoint with the dynamic path /:template.json that returns a JSON response with keys the same as custom providers.

Because of the simplicity, you can even use a GitHub repository as a template registry but also you can build something more powerful by bringing your own API.

Usage (Programmatic)

Install package:

# npm
npm install giget

# yarn
yarn install giget

# pnpm
pnpm install giget

Import:

// ESM
import { downloadTemplate } from "giget";

// CommonJS
const { downloadTemplate } = require("giget");

downloadTemplate(source, options?)

Example:

const { source, dir } = await downloadTemplate("github:unjs/template");

Options:

Return value:

The return value is a promise that resolves to the resolved template.

Custom Providers

Using the programmatic method, you can make your custom template providers.

import type { TemplateProvider } from "giget";

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 downloadTemplate("rainbow:one", {
  providers: { rainbow },
});

Custom Registry Providers

You can define additional custom registry providers using registryProvider utility and register to providers.

import { registryProvider } from "giget";

const themes = registryProvider(
  "https://raw.githubusercontent.com/unjs/giget/main/templates",
);

const { source, dir } = await downloadTemplate("themes:test", {
  providers: { themes },
});

Providing token for private repositories

For private repositories and sources, you might need a token. In order to provide it, using CLI, you can use --auth, using programmatic API using auth option and in both modes also it is possible to use GIGET_AUTH environment variable to set it. The value will be set in Authorization: Bearer ... header by default.

Note: For github private repository access with Fine-grained access tokens, you need to give Contents and Metadata repository permissions.

Related projects

Giget wouldn't be possible without inspiration from former projects. In comparison, giget does not depend on any local command which increases stability and performance and supports custom template providers, auth, and many more features out of the box.

💻 Development

License

Made with 💛

Published under MIT License.

<!-- Badges -->