GitHub Contributor Covenant

Monorepo for @funish/basis - A unified development toolkit with CLI for package management, versioning, publishing, linting, and git hooks management for JavaScript/TypeScript projects.

This is the monorepo for @funish/basis, a modern development toolkit that unifies common development workflows into a single CLI. Instead of juggling multiple tools for package management, versioning, publishing, linting, and git hooks, Basis provides one interface for everything.

👤 User? Looking to use @funish/basis? Check out the package documentation or install directly:

# Install globally with pnpm (recommended)
pnpm add -g @funish/basis
# Quick start
basis init

🧑‍💻 Developer? Welcome! This document is for you. Keep reading to learn how to contribute to this project.

Basis is a unified CLI toolkit that provides:

• 📦 Package Management: Auto-detected package manager support (npm, yarn, pnpm, bun, deno)
• 🏷️ Version Management: Semantic versioning with automated git tagging
• 🚀 Publishing: Multi-tag publishing strategy with edge version tracking
• 🔧 Linting: Tool-agnostic linting workflow
• 🪝 Git Hooks: Smart git hooks management
• 💻 Modern Architecture: Built on unjs ecosystem (citty, consola, c12, nypm, semver)

basis/
├── packages/
│ └── basis/ # Main @funish/basis package
│ ├── src/
│ │ ├── cli.ts # CLI entry point
│ │ ├── commands/ # CLI command implementations
│ │ │ ├── install.ts # Package installation (nypm)
│ │ │ ├── add.ts # Add dependencies (nypm)
│ │ │ ├── remove.ts # Remove dependencies (nypm)
│ │ │ ├── run.ts # Run scripts (nypm)
│ │ │ ├── version.ts # Version management (semver)
│ │ │ ├── publish.ts # Publishing workflow
│ │ │ ├── lint.ts # Linting coordination
│ │ │ ├── git.ts # Git management with subcommands
│ │ │ ├── init.ts # Project initialization
│ │ │ └── config.ts # Configuration management
│ │ ├── modules/ # Core business logic
│ │ │ ├── version.ts # Version management logic
│ │ │ ├── publish.ts # Publishing logic
│ │ │ ├── git.ts # Git hooks and config implementation
│ │ │ ├── lint.ts # Linting implementation
│ │ │ └── init.ts # Initialization logic
│ │ ├── config.ts # Configuration system (c12)
│ │ ├── types.ts # TypeScript type definitions
│ │ └── utils.ts # Shared utilities
│ ├── package.json # Package manifest
│ ├── build.config.ts # Build configuration (unbuild)
│ └── README.md # User documentation
├── package.json # Monorepo configuration
├── pnpm-workspace.yaml # pnpm workspace configuration
├── tsconfig.json # TypeScript configuration
├── basis.config.ts # Self-hosting configuration
└── README.md # This file (development documentation)

• Node.js 18.x or higher
• pnpm 9.x or higher (this project uses pnpm as the package manager)
• Git for version control

1. Clone the repository:

   git clone https://github.com/funish/basis.git
   cd basis

2. Install dependencies:

   pnpm install

3. Build packages:

   pnpm build

4. Development mode (watch and rebuild):

   pnpm dev

5. Test the CLI locally:

   # Link the package globally for testing
   cd packages/basis
   pnpm link --global
   # Now you can use 'basis' command anywhere
   basis --version

pnpm dev # Watch and rebuild (recommended for development)
pnpm build # Build all packages for production
pnpm lint # Run code formatting and linting

The codebase is organized into clear layers:

• Commands (src/commands/): CLI interface using citty
• Modules (src/modules/): Business logic implementation
• Configuration (src/config.ts): Unified config system using c12
• Types (src/types.ts): TypeScript definitions
• Utilities (src/utils.ts): Shared helper functions

• citty : Modern CLI framework for command structure
• consola : Elegant console logging
• c12 : Universal configuration loader
• nypm : Universal package manager interface
• semver : Semantic versioning utilities
• pkg-types : Package.json utilities
• pathe : Universal path utilities
• micromatch : Pattern matching for linting

Uses c12 for powerful configuration loading with:

• TypeScript support
• Environment-based overrides
• Schema validation
• Unified configuration file (basis.config.ts)

Multi-tag publishing approach:

• edge: Always points to latest published version
• latest: Stable releases only
• alpha/beta/rc: Prerelease channels
• Custom tags: Flexible workflow support

We welcome contributions! Here's how to get started:

# Clone and setup
git clone https://github.com/funish/basis.git
cd basis
pnpm install
pnpm dev
# Test your changes
cd packages/basis && pnpm link --global
basis --version

1. Code: Follow our standards in CONTRIBUTING.md
2. Test: pnpm build && basis <your-command>
3. Commit: Use conventional commits (feat:, fix:, etc.)
4. Submit: Create a Pull Request

📋 For detailed guidelines, principles, and best practices, see our Contributing Guide.

This project uses itself for version management and publishing:

# Create a new version
basis version patch # or minor/major
# Publish to npm
basis publish --stable # for stable release
basis publish # for edge release

• Patch: Bug fixes, small improvements
• Minor: New features, backwards compatible
• Major: Breaking changes
• Prerelease: Alpha/beta releases with basis version --prerelease

This monorepo uses its own basis configuration:

// basis.config.ts
export default defineBasisConfig({
 lint: [
 { runner: "oxlint" },
 { runner: "tsc" },
 ],
 fmt: [
 { runner: "oxfmt" },
 ],
 check: {
 staged: {
 "*.{ts,js,json}": "basis lint",
 "*.{ts,js,json,md}": "basis fmt",
 },
 },
 git: {
 hooks: {
 "pre-commit": "pnpm basis check --staged",
 "commit-msg": "pnpm basis git --lint-commit",
 },
 config: {
 core: {
 autocrlf: "input",
 },
 },
 autoInitGit: true,
 },
 version: {
 tagPrefix: "v",
 autoCommit: true,
 autoTag: true,
 autoPush: false,
 },
 publish: {
 defaultTag: "edge",
 stableTag: "latest",
 checkGitClean: true,
 checkTests: true,
 },
});

Basis follows core principles that guide its design and development:

1. Unified Interface: One CLI for all development tasks
2. Tool Agnostic: Don't replace tools, orchestrate them
3. Auto-Detection: Minimize configuration, maximize convenience
4. Modern Stack: Built on proven unjs ecosystem
5. Developer Experience: Focus on productivity and simplicity
6. Balanced Output: Silent process with clear completion status

📋 For detailed development principles and coding standards, see our Contributing Guide.

The unjs ecosystem provides:

• Consistency: Similar APIs across tools
• Quality: Well-tested, maintained packages
• Performance: Optimized for speed and bundle size
• Community: Active development and support

• 📫 Report Issues
• 💬 Discussions
• 📚 Documentation

This project is licensed under the MIT License - see the LICENSE file for details.

Built with ❤️ by Funish using the amazing unjs ecosystem