Contributing

RequirementsCopy Anchor Link

Turborepo reads the packageManager field to identify the package manager. Install Bun itself with the official install script or with npm i -g bun@1.4.4, not with Corepack. For the commands on each operating system, see Run from Source.

Repository layoutCopy Anchor Link

Common commandsCopy Anchor Link

Run these commands in the repository root:

To run a task for one package only, use the Turborepo --filter option:

bunx turbo run dev --filter=@kuma-mieru/web

The dev script of the web application runs generate first. Thus you must create apps/web/.env before you start development. For the procedure, see Run from Source.

Web application scriptsCopy Anchor Link

Run these commands in the apps/web directory:

Code styleCopy Anchor Link

• Use Valibot for data validation.
• Write all code in TypeScript. Keep the code short and easy to read.
• Use functional and declarative patterns. Obey the DRY principle. Use early returns to reduce nesting.
• Organize a component file in this order: exports, subcomponents, helpers, types.
• Give boolean names an auxiliary verb, for example isLoading and hasError.
• Start event handler names with handle, for example handleClick and handleSubmit.
• Use lowercase letters and dashes for directory names, for example components/auth-wizard.
• Prefer named exports for components.
• Prefer interfaces. Use const maps instead of enums. Use the satisfies operator to validate types.
• Use React Server Components where possible and keep 'use client' directives to a minimum. Add error boundaries to components. Use Suspense for asynchronous operations.

InternationalizationCopy Anchor Link

Interface translations are in apps/web/messages/, one JSON file for each language, for example apps/web/messages/en-US.json. To add a language:

1. Add the language to the locales array in apps/web/utils/i18n/config.ts.
2. Add the translation file of the language to apps/web/messages/.
3. Register the import of the translation file in messageLoaders in apps/web/utils/i18n/messages.ts. Kuma Mieru cannot load the translations of a language that is not registered.
4. To show a flag in the language menu, add the matching flag component from @sankyu/react-circle-flags to the flagComponents maps in apps/web/components/basic/i18n-switch.tsx and apps/web/app/global-error.tsx. Use the alpha2Code of the language as the key.

Submit a pull requestCopy Anchor Link

git clone https://github.com/YOUR-USERNAME/kuma-mieru.git
cd kuma-mieru
git remote add upstream https://github.com/Alice39s/kuma-mieru.git
bun install

git checkout -b feature/amazing-feature

bun run lint
bun run format

git commit -m 'feat(component): add some amazing feature'

git push origin feature/amazing-feature

A pull request must meet these requirements:

• Each pull request addresses one issue or one feature.
• The description states clearly what the pull request does.
• Interface changes include screenshots when possible.
• The code passes all lint and format checks.
• The changes work in both the light and the dark theme.
• The pull request stays current with the main branch through rebase.

Tests and documentationCopy Anchor Link

• Write tests for your code when applicable and run them with bun run test. Your changes must not break existing features.
• If your changes affect the features, update README.md, README.en.md and the matching pages in apps/docs/content/docs. Update both the Chinese file (page.mdx) and the English file (page.en.mdx).
• Add comments that describe the purpose of your components.