Build a template downloader

Write a script that downloads a repository into downloaded-template/. Run it twice to see how the cache works.

In an empty directory, initialize a package:

bun init -y

npm init -y

pnpm init

yarn init -y

Install the downloader:

bun add @hulla/gittar@0.0.4

npm install @hulla/gittar@0.0.4

pnpm add @hulla/gittar@0.0.4

yarn add @hulla/gittar@0.0.4

Create download.ts at the project root. Keeping the cache in this project makes it easy to inspect the two directories:

import gittar from '@hulla/gittar'
import { resolve } from 'node:path'

const snapshot = await gittar({
  url: 'hulladev/gittar',
  branch: 'master',
  cacheDir: resolve('.cache/gittar/master'),
  outDir: resolve('downloaded-template'),
})

console.log(snapshot.fromCache ? 'Used cache' : 'Downloaded')
console.log(`Copied ${snapshot.files.length} files to ${snapshot.outDir}`)

url selects the repository. branch selects the ref to download. outDir keeps the editable copy separate from the cache.

Run the script with Bun, even if you used another package manager to install it:

bun download.ts

The first run prints Downloaded and a file count. Open downloaded-template/package.json: it should name @hulla/gittar. The cache directory contains the full extracted repository and its metadata.

Run the same command again. If the remote branch hasn’t changed and the cache is intact, it prints Used cache. The default policy still contacts the remote to check the commit; a cache hit doesn’t mean an offline run.

Add this property to the same config object when you want to reuse the local snapshot without a remote freshness check:

update: 'never',

Run bun download.ts again. It uses the existing cache. On a fresh machine, never still downloads because no snapshot exists yet.

You now have the download stage of a scaffolding tool. Next, copy one folder or handle stale snapshots. For command-line options such as --destination, add an @hulla/args parser around this script.