https://github.com/stacksjs/gitit

A simple way to download templates stored using git.
https://github.com/stacksjs/gitit

download git starter-kit templates

Last synced: about 1 year ago
JSON representation

A simple way to download templates stored using git.

Host: GitHub
URL: https://github.com/stacksjs/gitit
Owner: stacksjs
License: mit
Created: 2025-04-21T21:19:02.000Z (about 1 year ago)
Default Branch: main
Last Pushed: 2025-05-06T04:08:19.000Z (about 1 year ago)
Last Synced: 2025-05-06T05:21:16.499Z (about 1 year ago)
Topics: download, git, starter-kit, templates
Language: TypeScript
Homepage: https://stacks-gitit.netlify.app
Size: 343 KB
Stars: 2
Watchers: 2
Forks: 0
Open Issues: 2
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Security: .github/SECURITY.md

Awesome Lists containing this project

README

          


[![npm version][npm-version-src]][npm-version-href]

[![GitHub Actions][github-actions-src]][github-actions-href]

[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)

# gitit

A powerful template and project scaffolding tool to help kick-start development of your next project.

## Features

Gitit comes with the following features:

- 🚀 **Fast Template Cloning** _Clone templates from GitHub, GitLab, Bitbucket, and more_

- 💪 **Fully Typed APIs** _Written in TypeScript for a great developer experience_

- 📦 **Zero Configuration** _Works out of the box with sensible defaults_

- 🔄 **Offline Support** _Use cached templates when offline_

- 🛠️ **Customizable** _Configure templates with various options_

- 🧩 **Post-Installation Commands** _Run custom commands after cloning_

- 🔑 **Private Repository Support** _Authentication for private templates_

- 🖥️ **Interactive Shell** _Open a shell in your newly created project_

## Get Started

```bash

# Install globally

bun install -g @stacksjs/gitit

# or use directly with bunx

bunx @stacksjs/gitit github:user/repo my-project

```

## Usage

```bash

# Basic usage

gitit github:user/repo my-project

# With options

gitit github:user/repo my-project --install --shell

# Clone with custom command

gitit github:user/repo my-project --command "npm run dev"

# Use offline cached template

gitit github:user/repo my-project --offline

# Clone to a specific directory

gitit github:user/repo ./path/to/project

```

## Available Options

| Option | Description |

|--------|-------------|

| `--force` | Clone to existing directory even if it exists |

| `--force-clean` | Remove any existing directory or file recursively before cloning |

| `--shell` | Open a new shell with current working directory |

| `--install` | Install dependencies after cloning |

| `--verbose` | Show verbose debugging info |

| `--command` | Custom command to run after template is cloned |

| `--auth` | Custom Authorization token for private repositories |

| `--cwd` | Set current working directory to resolve dirs relative to it |

| `--offline` | Do not attempt to download and use cached version |

| `--prefer-offline` | Use cache if exists otherwise try to download |

## Library Usage

Gitit can also be used programmatically in your Node.js or Bun applications:

```js

import { downloadTemplate } from '@stacksjs/gitit'

// Basic usage

await downloadTemplate('github:user/repo')

// With options

const result = await downloadTemplate('github:user/repo', {

  dir: './my-project',

  force: true,

  install: true,

  offline: false,

  preferOffline: true

})

console.log(`Downloaded to ${result.dir}`)

```

### API Reference

#### `downloadTemplate(source, options)`

The main function for downloading templates.

- **source**: `string` - Template source (e.g., "github:user/repo")

- **options**: `DownloadTemplateOptions` - Configuration options

```ts

interface DownloadTemplateOptions {

  provider?: string // Specify provider (github, gitlab, etc.)

  force?: boolean // Force clone even if directory exists

  forceClean?: boolean // Remove existing directory before cloning

  offline?: boolean // Use cached version only

  preferOffline?: boolean // Prefer cache if exists

  dir?: string // Target directory

  registry?: false | string // Registry URL or false to disable

  cwd?: string // Current working directory

  auth?: string // Auth token for private repositories

  install?: boolean // Install dependencies after download

  silent?: boolean // Hide installation output

  hooks?: Hooks // Custom lifecycle hooks

}

```

#### Return value

```ts

interface DownloadTemplateResult {

  dir: string // The directory where template was extracted

  source: string // Original source string

  name: string // Template name

  tar: string // Tarball URL

  version?: string // Template version

  url?: string // Repository URL

  // ... additional properties

}

```

#### Advanced: Custom Plugins

You can extend gitit's functionality using plugins:

```js

import { downloadTemplate } from '@stacksjs/gitit'

const myPlugin = {

  name: 'my-plugin',

  version: '1.0.0',

  hooks: {

    afterExtract: (result) => {

      console.log(`Template extracted to ${result.dir}`)

      return result

    }

  },

  providers: {

    myCustomSource: (input, options) => {

      // Custom template provider logic

      return {

        name: 'my-template',

        tar: 'https://example.com/template.tar.gz'

      }

    }

  }

}

await downloadTemplate('mycustom:template', {

  plugins: [myPlugin]

})

```

## Changelog

Please see our [releases](https://github.com/stackjs/gitit/releases) page for more information on what has changed recently.

## Contributing

Please see [CONTRIBUTING](.github/CONTRIBUTING.md) for details.

## Community

For help, discussion about best practices, or any other conversation that would benefit from being searchable:

[Discussions on GitHub](https://github.com/stacksjs/gitit/discussions)

For casual chit-chat with others using this package:

[Join the Stacks Discord Server](https://discord.gg/stacksjs)

## Postcardware

"Software that is free, but hopes for a postcard." We love receiving postcards from around the world showing where Stacks is being used! We showcase them on our website too.

Our address: Stacks.js, 12665 Village Ln #2306, Playa Vista, CA 90094, United States 🌎

## Sponsors

We would like to extend our thanks to the following sponsors for funding Stacks development. If you are interested in becoming a sponsor, please reach out to us.

- [JetBrains](https://www.jetbrains.com/)

- [The Solana Foundation](https://solana.com/)

## License

The MIT License (MIT). Please see [LICENSE](LICENSE.md) for more information.

Made with 💙

[npm-version-src]: https://img.shields.io/npm/v/@stacksjs/gitit?style=flat-square

[npm-version-href]: https://npmjs.com/package/@stacksjs/gitit

[github-actions-src]: https://img.shields.io/github/actions/workflow/status/stacksjs/gitit/ci.yml?style=flat-square&branch=main

[github-actions-href]: https://github.com/stacksjs/gitit/actions?query=workflow%3Aci

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/stacksjs/gitit

Awesome Lists containing this project

README