Skip to main content

​
Prerequisites

Before you begin development with TailStack, ensure your environment meets the following requirements:

​
Node.js Version

TailStack requires Node.js 24.13.0 for optimal compatibility. The repository includes version configuration files to ensure consistency across all developers:
  • .nvmrc - For NVM (Node Version Manager) users
  • .node-version - For asdf and other version managers
Both files specify: 
24.13.0
1
Install Node.js 24.13.0
2
Using NVM (Recommended)
# Install and use the correct Node version
nvm install
nvm use
The .nvmrc file will automatically be detected.
Using asdf
# Install and set the Node version
asdf install nodejs 24.13.0
asdf local nodejs 24.13.0
Manual Installation
Download Node.js 24.13.0 from the official website.
3
Install PNPM
4
TailStack uses PNPM 10.12.1 as its package manager, specified in package.json:
5
"packageManager": "[email protected]"
6
Install PNPM globally:
7
# Using npm
npm install -g [email protected]

# Or using Corepack (recommended)
corepack enable
corepack prepare [email protected] --activate
8
Corepack is included with Node.js 16.13+ and automatically manages package manager versions based on your package.json.
9
Verify Installation
10
Check that everything is installed correctly:
11
node --version  # Should output: v24.13.0
pnpm --version  # Should output: 10.12.1

​
PNPM Configuration

TailStack includes a .npmrc file at the root with the following settings: 
auto-install-peers=true
strict-peer-dependencies=true

​
Configuration Explained

  • auto-install-peers=true - Automatically installs peer dependencies, reducing manual intervention
  • strict-peer-dependencies=true - Enforces strict peer dependency resolution to catch version conflicts early
Do not modify the .npmrc file unless you understand the implications. These settings ensure consistent dependency resolution across the monorepo.

​
Git Hooks Setup

TailStack uses Husky and lint-staged to enforce code quality and security standards automatically.

​
Initialize Husky

After cloning the repository, initialize Husky hooks: 
pnpm husky
This command runs pnpm exec husky init and sets up the Git hooks in the .husky/ directory.

​
Pre-commit Hook

The pre-commit hook (.husky/pre-commit) runs security checks before every commit: 
#!/usr/bin/env sh

if [ -d "/c/ProgramData/chocolatey/bin" ]; then
  export PATH="/c/ProgramData/chocolatey/bin:$PATH"
fi

echo "🔍 Running pre-commit security checks..."
pnpm lint-staged
What it does:
  • Runs Gitleaks to scan staged files for secrets and credentials
  • Automatically redacts sensitive information if detected
  • Prevents commits containing secrets from entering your Git history

​
Commit Message Hook

The commit-msg hook (.husky/commit-msg) validates commit message format: 
#!/usr/bin/env sh

pnpm commitlint --edit "$1"
What it does:
  • Enforces Conventional Commits format
  • Ensures consistent commit history for automated changelog generation
  • Validates against rules defined in commitlint.config.cjs

​
Commitlint Configuration

TailStack extends the conventional commits standard with custom limits: 
module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'header-max-length': [2, 'always', 150],
    'body-max-line-length': [2, 'always', 250],
  },
};
Valid commit message examples: 
feat: add user authentication module
fix: resolve memory leak in WebSocket connection
docs: update API documentation
refactor: optimize database query performance
test: add unit tests for payment processing
Use conventional commit prefixes:
  • feat: - New features
  • fix: - Bug fixes
  • docs: - Documentation changes
  • refactor: - Code refactoring
  • test: - Adding or updating tests
  • chore: - Maintenance tasks

​
Editor Configuration

TailStack includes an .editorconfig file to maintain consistent coding styles: 
root = true

[*]
end_of_line = lf
insert_final_newline = true
charset = utf-8
trim_trailing_whitespace = true

[*.{js,jsx,ts,tsx,css,json}]
indent_style = space
indent_size = 2

[*.html]
indent_style = space
indent_size = 2

[*.md]
trim_trailing_whitespace = false
indent_style = space
indent_size = 2
Supported editors:
  • VS Code (install EditorConfig extension)
  • JetBrains IDEs (built-in support)
  • Sublime Text (install EditorConfig plugin)
  • Vim/Neovim (install editorconfig-vim)

​
Security Tools

TailStack includes Gitleaks for secret detection: 
"lint-staged": {
  "*": [
    "gitleaks protect --staged --redact"
  ]
}
Gitleaks configuration is defined in .gitleaks.toml with custom rules for:
  • API keys
  • Database credentials
  • JWT tokens
  • Private keys
  • OAuth secrets
Important: Never bypass Git hooks with --no-verify unless absolutely necessary. The hooks exist to protect your codebase and prevent security vulnerabilities.

​
Troubleshooting

​
Husky hooks not running

If Git hooks aren’t executing: 
# Reinstall Husky
pnpm husky

# Make hooks executable (Unix-based systems)
chmod +x .husky/*

​
PNPM installation fails

If you encounter peer dependency issues: 
# Clear PNPM cache
pnpm store prune

# Remove node_modules and reinstall
pnpm clean  # Uses TailStack's clean script
pnpm install

​
Wrong Node version

Ensure you’re using the correct Node version: 
# Check current version
node --version

# Switch to correct version (NVM)
nvm use

# Or set it as default
nvm alias default 24.13.0

​
Next Steps

Now that your environment is set up:
  1. Review available automation scripts for managing the monorepo
  2. Learn the development workflow for running dev servers
  3. Explore customization options to tailor TailStack to your needs

Build docs developers (and LLMs) love

Get started for freeTalk to us