Giraffe🦒

A template to quickly 📦 any typescript library/project using high industry standards!

Get Started  •  Semantic Versioning  •  Development

Toolchain
pnpm	package manager
TypeScript	language
ESLint	linter
Vite	build tool
Vitest	unit testing
Changesets	changelog
Renovate	package upgrading

Who is this for?

Those who are planning to

• create a scalable project using Vite
• build any library using typescript

Standardizations

• Continous Integration
• Semantic Versioning
• Conventional Messages
• Pull Request -> Squash & Merge
• Changesets: Changelogs and auto-publishing
• Linting, testing, typechecking

FAQ

Q: Why a Monorepo?

This template seperates concerns. We can have a demo and/or documentation website live in `apps/*` — but we also seperate the toolchain. The package will only contain dependencies that's relevant to the package.

The template can both be used for a small library, or a large project making it versatile. So, as long you are working in node.js, this template will suit you perfectly.

Q: Giraffe?

Giraffes are a symbol of adaptation. With their long necks, they reach new heights, see things from a different perspective, and look for solutions in places you otherwise wouldn't. Their height makes them alert, allowing them to see trouble from far away.

Let us aspire to be like giraffes in a demanding market, creating robust, scalable and maintainable solutions.

Get Started

Clone project to the current folder

npx degit refzlund/giraffe

Create your repository

• Initialize a new git repository
• Commit & push to your new repository

Configure repository

• Auto-publishing:
  • Provide a repository secret:  NPM_TOKEN,  for auto-publishing via github workflows
    https://github.com/<owner/repo>/settings/secrets/actions
  • Uncomment action at .github/workflows/publish.yml
• Activate renovate and changesets for your repository
• Change Pull Requests to only allow Squash: Default to pull request title
https://github.com/<owner/repo>/settings#merge-button-settings
• Create branch protection at
  https://github.com/<owner/repo>/settings/branch_protection_rules/new
  and enable:
  • Require a pull request before merging
    • Untick 'Require approvals'
  • Require status checks to pass before merging
    • Add test to the list of required status checks
  • Allow force pushes
    • Specify who can force push ^{*will allow administrators automatically}
• Allow workflow Read and write permissions
  https://github.com/<owner/repo>/settings/actions
  • Below ^, tick on 'Allow GitHub Actions to create and approve pull requests'

Create branch

Let's set a good first example, and create a branch for configurating our project.

We will push changes one by one into our new branch.

Create a branch following Semantic Changes:  chore-configurating-initial-project

Configure your library

• Find & Replace <repo> with your repository
  • Example: <repo> -> x-classes
• Find & Replace <owner/repo> with your owner/repository
  • Example: <owner/repo> -> refzlund/x-classes
• Rename packages/template to <repo>, ex. -> packages/x-classes
• Configure your packages/<repo>/package.json
• Define your monorepo README
• Define your library package README

Changelog!

Great! We've configured our project. Let's create our first patch release using changeset.

pnpm i

• Create changeset: 
  1. npx changeset
  2. Select your package using space, enter to continue
  3. No major changes
  4. No minor changes
  5. Patch — chore: configurating initial project
• Push your changes
• Create pull request on the main branch for chore-configurating-initial-project
  • Title: chore: configurating initial project
• Squash & Merge changes

When you're ready to publish a new release, merge the incoming "Version Packages"-pull request by changesets.

Congratsulations! You're a natural🚀🎉

Development

See Development

Community tips & tricks

Note

Pull requests and issues to this repository are more than welcome🦒

• Shield.io: Spice up your README.md using badges
  • GitHub Release badge
• Paths in tsconfig.json allows you to import aliases
• Complex projects can use Docker containers to make setting up a project take 5 minutes instead of 5 hours
• Cache your project using Turbo Monorepo and Caching it via GitHub Actions

VSCode Extensions

• Toggle Excluded Files: Hide unnecessary config files
• ESLint: Integrates ESLint into VS Code
• Vitest Runner: Run your Vitests with a single click
  • It launches the terminal.
    After — press arrow up — replace vitest run ... with vitest watch ..., and it will run the tests when the files change.
• Console Ninja: Outputs console logs in your IDE — immensly helpful debugging tool

Get Inspired

Here are some repositories that follow similar structure:

• sveltejs/kit