ecomfe/vue-echarts ⭐ 10,597

# Repository Guidelines

## Project Structure & Module Organization

Core source lives in `src/`, implemented in TypeScript with the Vue 3 Composition API and ESM. Key entry modules include `src/index.ts` for exports, `src/ECharts.ts` for the main component, and related helpers in `src/composables/`, `src/utils.ts`, `src/types.ts`, and `src/update.ts`. Global/CE entrypoints live in `src/global.ts` and `src/wc.ts`. Styles are defined in `src/style.css` and injected via `src/style.ts`. Demo assets sit in `demo/` (Vite-powered) and should be kept in sync with new features. Tests live under `tests/` with separate browser/node projects. Bundled artifacts in `dist/` are generated by `pnpm build`; avoid editing them manually. Shared build helpers reside in `scripts/`.

## Build, Test, and Development Commands

Use `pnpm install` to set up dependencies. `pnpm dev` serves the demo playground at `http://localhost:5173` for interactive testing; use `pnpm dev:build` or `pnpm dev:preview` for the Vite demo bundle, and `pnpm dev:typecheck` to typecheck the demo. Run `pnpm build` (tsdown) to produce distributable output under `dist/`. `pnpm typecheck` runs library typechecks for both the main and Vitest configs. `pnpm lint` (or `pnpm lint:fix`) applies ESLint, `pnpm format` runs oxfmt, and `pnpm test` executes the Vitest suite (see also `pnpm test:browser`, `pnpm test:node`, and `pnpm test:coverage`). Install Playwright Chromium with `pnpm test:setup` when running browser tests. Use `pnpm publint` before releases, and `pnpm docs` to refresh generated docs content.

## Coding Style & Naming Conventions

This project targets Vue 3 + TypeScript with ECMAScript modules. Follow the existing 2-space indentation and trailing commas where valid; let oxfmt handle string quote style (currently double quotes). Components and exported composables use PascalCase (e.g., `VChart`), while local helpers remain camelCase. Honor `eslint.config.ts` and oxfmt defaults; always run `pnpm lint && pnpm format` before sending patches. Keep public exports centralized in `src/index.ts` and add accompanying CSS changes to `src/style.css` (the runtime injection happens in `src/style.ts`).

## Testing Guidelines

For complete and up-to-date testing and CI guidance, see [`tests/TESTING.md`](tests/TESTING.md).

## Commit & Pull Request Guidelines

Commit history follows Conventional Commits (`type(scope): summary`), e.g., `feat(runtime): add renderer option` or `chore(deps): update vue`. Use concise, imperative summaries and group related changes together. PRs should describe user-facing effects, list verification commands, and link issues with `Fixes #123` when applicable. Include screenshots or GIFs for visual updates to the demo, and note any doc changes (`README.md`, `demo/`) in the description. Ensure CI checks mirror local commands: `pnpm lint`, `pnpm typecheck`, and `pnpm build`.