# Contributing The repository is released under the MIT license, and follows a standard Github development process, using Github tracker for issues and merging pull requests into main. ## Requirements * Node.js `^22.22.2 || ^24.15.0 || >=26.0.0`, the same range as `engines` in `package.json`; jsdom and stylelint set that floor * npm 10+ `.npmrc` sets `engine-strict=true`, so `npm install` / `npm ci` fail with a clear message on an unsupported Node.js instead of breaking halfway through a build. `Test CI` runs the matrix on the latest 22 and 24, plus a `test (node floor)` job pinned to 22.22.2 that fails as soon as a dependency raises its own floor above the advertised range. ## Development ```shell $ npm install $ npm run dev # Vite dev server, opens static/index.html $ npm run type-check # tsc --noEmit over src, __test__, tasks and the configs $ npm run lint # ESLint (flat config, @antfu/eslint-config) $ npm run lint:style # Stylelint for src/**/*.{css,scss} $ npm test # Vitest $ npm run package # build dist/ and assemble .release/ ``` `static/index.html` is the only page: it imports `src/` directly, so the dev server and the GitHub Pages demo share it. `npm run dev` opens `/static/index.html`; `build:deployment` builds that same file with `static/` as the Vite root, which is what puts `index.html` at the root of the `.publish` artifact. ## TypeScript specifics * `tsconfig.json` type-checks everything (`noEmit`) and is the config the CI `type-check` step uses. `tsconfig.build.json` is the declaration-only config that writes `dist/index.d.ts` during the build. * `tasks/*.ts` are executed by Node's built-in type stripping, so they may only use syntax that can be erased: no `enum`, `namespace` or constructor parameter properties. `erasableSyntaxOnly` enforces this during `type-check`, and Node's ESM resolver requires relative imports to carry the `.ts` extension. * `release.config.js` stays JavaScript on purpose: semantic-release loads it through cosmiconfig, whose TypeScript loader resolves `typescript` from semantic-release's own install tree (inside the action) rather than from this project. * `src/types/*.d.ts` holds the ambient declarations for CSS Modules, `@cycjimmy/config-lib` and `@cycjimmy/awesome-js-funcs`, none of which ship types. `src/types/swiper.ts` describes Swiper structurally on purpose: the published declarations must not depend on a consumer's `swiper` install. * `__test__/type-contract.ts` is a compile-only file: `type-check` fails if the declarations stop accepting a documented consumer usage (swiper's own options type, synchronous and asynchronous `Popup.load()` overrides, `Page` subclass hooks). It is not matched by Vitest's `*.test.ts` pattern. * A global stylesheet must not be imported for its side effects from `src/index.ts`: that import is re-emitted into `dist/index.d.ts` and points at a file that is not published. `src/theme/base.scss` is pulled into `src/root/root.module.scss` with `@use` instead. ## Build outputs `npm run build` writes four artifacts into `dist/`: | File | Format | Purpose | | --- | --- | --- | | `dist/h5-pages.esm.js` | ESM | `main`, `module` and `exports` entry (bundlers, `import`) | | `dist/h5-pages.umd.js` | UMD | unminified browser build for `