diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 000000000..80bc6a279 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,214 @@ +# Frappe UI - Copilot Instructions + +## Overview + +Frappe UI is a Vue 3 component library and UI framework for rapidly building modern frontends for Frappe apps. It provides reusable components, data-fetching utilities, directives, and Tailwind-based styling. + +**Repository Type**: NPM Package / Vue 3 Component Library +**Primary Languages**: TypeScript, Vue, JavaScript +**Framework**: Vue 3 +**Styling**: TailwindCSS +**Build Tool**: Vite +**Package Manager**: Yarn (v1.22.22) +**Node Version**: v20.x (CI uses Node 20 and 22) + +## Build & Development Commands + +**IMPORTANT**: Always use Yarn (not npm) for all package management and script execution. + +### Dependencies Installation +```bash +yarn install --frozen-lockfile +``` +Always use `--frozen-lockfile` flag to ensure consistent dependency versions. + +### Testing +```bash +yarn test +``` +- Runs Vitest test suite in run mode (non-watch) +- Tests are located in `src/data-fetching/` subdirectories with `.test.ts` suffix +- Uses MSW (Mock Service Worker) for API mocking +- Test setup file: `vitest.setup.ts` +- All tests must pass before publishing + +### Type Checking +```bash +yarn type-check +``` +- Runs TypeScript compiler in no-emit mode +- **Known Issue**: Type checking currently has errors related to generated `.d.ts` files in `src/mocks/` directory +- These errors are pre-existing and should not block PRs unless you're modifying TypeScript configuration + +### Building +```bash +yarn build +``` +- Uses Vite to build the library +- Outputs to `dist/` directory +- Build time: ~8-10 seconds +- **Note**: You may see a Browserslist warning - this is informational only + +### Development Server +```bash +yarn dev +``` +Starts Vite development server for local development. + +### Component Story Development +```bash +yarn story:dev # Start Histoire dev server +yarn story:build # Build Histoire documentation +yarn story:preview # Preview built Histoire +``` +Histoire is used for component documentation and visual testing. + +### Code Formatting +```bash +yarn prettier +``` +- Automatically formats code using Prettier +- Configured with Tailwind CSS plugin +- Pre-commit hooks run Prettier automatically (see `.pre-commit-config.yaml`) + +## Project Structure + +``` +frappe-ui/ +├── .github/ +│ └── workflows/ # CI/CD workflows +│ ├── vitest.yml # Runs tests on push/PR +│ ├── publish.yml # NPM publish on main branch +│ └── story-publish.yml +├── src/ +│ ├── components/ # Vue components (Button, Dialog, etc.) +│ ├── composables/ # Vue composables +│ ├── data-fetching/ # Data fetching utilities (useDoc, useList, etc.) +│ ├── directives/ # Vue directives +│ ├── resources/ # Resource management +│ ├── utils/ # Utility functions +│ ├── mocks/ # MSW test mocks +│ ├── fonts/ # Font files +│ └── style.css # Main stylesheet +├── frappe/ # Frappe-specific utilities +├── icons/ # Icon utilities +├── tailwind/ # Tailwind configuration +├── vite/ # Vite plugins +├── package.json +├── vite.config.ts +├── vitest.config.ts +├── tsconfig.json +└── histoire.config.ts +``` + +### Key Directories + +- **src/components/**: Vue 3 components organized by component name. Each component typically has its own directory with the main `.vue` file +- **src/data-fetching/**: Composables for fetching data from Frappe backend (`useDoc`, `useList`, `useCall`, `useDoctype`) +- **src/utils/**: Utility functions including Tailwind config preset +- **frappe/**: Core utilities for interacting with Frappe framework backend + +## Configuration Files + +- **vite.config.ts**: Vite configuration with Vue plugin and Lucide icons +- **vitest.config.ts**: Vitest test configuration with global test mode +- **tsconfig.json**: TypeScript configuration with path aliases (`@/*` → `src/*`) +- **tailwind.config.js**: Tailwind CSS configuration (also provides preset for consumers) +- **histoire.config.ts**: Histoire (component documentation) configuration +- **.pre-commit-config.yaml**: Pre-commit hooks for Prettier formatting + +## GitHub Actions / CI + +### Test Workflow (`.github/workflows/vitest.yml`) +- **Triggers**: Push to main, PRs to main +- **Node Version**: 22 +- **Steps**: + 1. Checkout code + 2. Setup Node with Yarn cache + 3. `yarn install --frozen-lockfile` + 4. `yarn test` + +### Publish Workflow (`.github/workflows/publish.yml`) +- **Triggers**: Push to main branch +- **Node Version**: 20 +- **Steps**: + 1. Update npm to latest + 2. `npm install` + 3. `npm test` + 4. `npm publish` +- **Note**: The publish workflow uses npm commands as configured in the CI environment for publishing to the NPM registry + +## Important Development Guidelines + +### Package Management +- **ALWAYS use Yarn** (never npm) for installing dependencies or running scripts +- Use `yarn add ` to add dependencies +- Use `yarn add -D ` for dev dependencies +- Use `--frozen-lockfile` when installing in CI or for reproducible builds + +### Code Style +- Prettier is enforced via pre-commit hooks (`.pre-commit-config.yaml`) for JavaScript and Vue files +- lint-staged (in `package.json`) also formats CSS and Markdown files on commit +- Tailwind CSS classes should be formatted with prettier-plugin-tailwindcss +- Files formatted on commit: `*.{js,css,md,vue}` + +### Component Development +- Components are Vue 3 Composition API based +- Use `