FoundryKit

Getting Started

Get started with FoundryKit CLI for project setup and management

Getting Started

Learn how to install and use the FoundryKit CLI to create and manage your projects efficiently.

Installation

Global Installation

Install the FoundryKit CLI globally to access it from anywhere on your system.

npm install -g @foundrykit/cli

Verify Installation

Check that the CLI is properly installed and accessible.

foundrykit --version

You should see output similar to:

@foundrykit/cli v1.0.0

Prerequisites

Before using the FoundryKit CLI, ensure you have the following installed:

  • Node.js (v18 or higher)
  • npm (v8 or higher) or yarn (v1.22 or higher)
  • Git (for version control)

Check Your Environment

# Check Node.js version
node --version

# Check npm version
npm --version

# Check Git version
git --version

Quick Start

Create a New Project

Create a new FoundryKit project with a single command.

foundrykit create my-project

This will:

  • Create a new directory with your project name
  • Set up the basic project structure
  • Install all necessary dependencies
  • Initialize Git repository
  • Create initial configuration files

Interactive Setup

For more control over your project setup, use the interactive mode.

foundrykit create my-project --interactive

This will prompt you for:

  • Project name and description
  • Package manager preference (npm, yarn, pnpm)
  • TypeScript configuration
  • Testing framework preference
  • Additional features to include

Project Structure

When you create a new project, the CLI generates the following structure:

package.json
tsconfig.json
tailwind.config.js
README.md

Basic Commands

Project Management

# Create a new project
foundrykit create <project-name>

# Initialize FoundryKit in existing project
foundrykit init

# Add a new component
foundrykit add component <component-name>

# Add a new page
foundrykit add page <page-name>

# Generate component documentation
foundrykit docs generate

Development Commands

# Start development server
foundrykit dev

# Build for production
foundrykit build

# Preview production build
foundrykit preview

# Run tests
foundrykit test

# Run linting
foundrykit lint

Configuration Commands

# Update FoundryKit configuration
foundrykit config update

# Show current configuration
foundrykit config show

# Reset configuration to defaults
foundrykit config reset

Configuration

FoundryKit Config File

The CLI creates a foundrykit.config.js file in your project root.

module.exports = {
  // Project configuration
  project: {
    name: 'my-project',
    version: '1.0.0',
    description: 'A FoundryKit project'
  },
  
  // Build configuration
  build: {
    outDir: 'dist',
    assetsDir: 'assets',
    sourcemap: true
  },
  
  // Development configuration
  dev: {
    port: 3000,
    host: 'localhost',
    open: true
  },
  
  // Component configuration
  components: {
    directory: 'components',
    prefix: '',
    style: 'css'
  }
}

Environment Variables

Create a .env file for environment-specific configuration.

# .env
FOUNDRYKIT_API_KEY=your_api_key_here
FOUNDRYKIT_ENVIRONMENT=development
FOUNDRYKIT_DEBUG=true

Package Manager Integration

npm

# Install dependencies
npm install

# Run scripts
npm run dev
npm run build
npm run test

yarn

# Install dependencies
yarn install

# Run scripts
yarn dev
yarn build
yarn test

pnpm

# Install dependencies
pnpm install

# Run scripts
pnpm dev
pnpm build
pnpm test

TypeScript Support

The CLI automatically configures TypeScript for your project.

TypeScript Configuration

{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "skipLibCheck": true,
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "react-jsx",
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true
  },
  "include": ["src"],
  "references": [{ "path": "./tsconfig.node.json" }]
}

Type Definitions

The CLI includes TypeScript definitions for all FoundryKit packages.

// Auto-generated types
import type { ButtonProps } from '@foundrykit/components'
import type { useLocalStorage } from '@foundrykit/hooks'

Testing Setup

Jest Configuration

The CLI sets up Jest for testing with React Testing Library.

// jest.config.js
module.exports = {
  testEnvironment: 'jsdom',
  setupFilesAfterEnv: ['<rootDir>/src/setupTests.ts'],
  moduleNameMapping: {
    '^@/(.*)$': '<rootDir>/src/$1'
  },
  collectCoverageFrom: [
    'src/**/*.{js,jsx,ts,tsx}',
    '!src/**/*.d.ts'
  ]
}

Example Test

// src/components/Button.test.tsx
import { render, screen } from '@testing-library/react'
import { Button } from './Button'

describe('Button', () => {
  it('renders correctly', () => {
    render(<Button>Click me</Button>)
    expect(screen.getByRole('button')).toBeInTheDocument()
  })
})

Linting and Formatting

ESLint Configuration

The CLI configures ESLint with React and TypeScript rules.

// .eslintrc.js
module.exports = {
  extends: [
    'eslint:recommended',
    '@typescript-eslint/recommended',
    'plugin:react/recommended',
    'plugin:react-hooks/recommended'
  ],
  parser: '@typescript-eslint/parser',
  plugins: ['@typescript-eslint', 'react'],
  rules: {
    'react/react-in-jsx-scope': 'off'
  }
}

Prettier Configuration

{
  "semi": false,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "es5"
}

Git Integration

Initial Setup

The CLI automatically initializes a Git repository and creates a .gitignore file.

# .gitignore
node_modules/
dist/
.env.local
.env.development.local
.env.test.local
.env.production.local
*.log

Commit Hooks

The CLI can set up pre-commit hooks for code quality.

# Install husky for git hooks
foundrykit setup hooks

Troubleshooting

Common Issues

CLI not found

# Reinstall globally
npm uninstall -g @foundrykit/cli
npm install -g @foundrykit/cli

Permission errors

# On macOS/Linux, use sudo
sudo npm install -g @foundrykit/cli

Node version issues

# Check Node version
node --version

# Use nvm to switch versions
nvm use 18

Getting Help

# Show help
foundrykit --help

# Show command-specific help
foundrykit create --help

# Check CLI version
foundrykit --version

Next Steps

CLI

Command-line interface for FoundryKit development and scaffolding

Command Reference

Complete reference for all FoundryKit CLI commands