The fact that you're reading this probably means you're interested in contributing to the Kitsu web application. If so, welcome! It's pretty easy to get started, and we're here to help you all the way. If you have any questions, please don't hesitate to ask us on our Discord in the #dev channel!
Before you make a pull request, please read the styleguide and make sure that you're keeping the codebase clean and consistent for future developers.
You're gonna need a fairly modern Node.js version. The Active LTS is probably the best option if you're not sure. Our deployments will use the Active LTS, but we try to ensure that everything runs smoothly on the Current version as well.
After you have Node, run the following:
npm install(installs dependencies)
npm run dev(default port 3000)
http://localhost:3000 and you should see the Kitsu application!
By default, in development mode, this will connect to
staging.kitsu.io(our pre-production environment) for the API, which means anything you do will be wiped out weekly. You can change this to connect to production if necessary by setting
.envfile. This is generally not necessary, but there are some things which don't work fully in staging.
In the future we plan to integrate this into the kitsu-tools dev environment better.
While the basic project structure should be familiar to most developers who have used React and Vite in the past, Kitsu is a large application and has more structure than you might be accustomed to.
Vite compiles the application starting at an "entry point". In our case, we have four, across three "build targets":
BUILD_TARGET=client— the main Kitsu (V4) web app
BUILD_TARGET=server— server-side rendered version of the Kitsu web app
server.js— main entry point for the Kitsu web app
BUILD_TARGET=library— a library of components from the Kitsu (V4) web app to expose for the V3 Ember app during migration.
src/entry-ember.tsx— the exports which will be accessible from the Ember application
src/assets/— static assets like icons, illustrations, and animations imported by the application. These aren't just copied to the output directory, these must be imported and can be processed during compilation with various plugins.
src/components/— common, reusable components
src/pages/— components rendering a whole page
src/layouts/— components providing a reusable page structure
src/contexts/— React contexts for sharing state between components
src/initializers/— imperative code which runs during app boot (avoid these if possible, prefer hooks in the App component)
src/constants/config.ts— exposes configuration to the application at runtime
src/graphql/— GraphQL support code, such as the generated schema types, scalars, and urql exchanges.
src/hooks/— custom react hooks for the application
src/locales/— data for every locale we support (translations, date-fn locales, etc.)
src/errors/— all our error subclasses
src/styles/— application-wide styles (not specific to a component), mostly in the form of variables which are used in component styles.
npm run codegen
If you change a
.gql file or add a new translation key, you will need to run
npm run codegen to
have them work properly. The GraphQL Codegen will generate typescript files for every query and the
Intl Codegen will extract all the translation keys from your components.
npm run storybook
We use Storybook to document components. We ask that you please document any new components you add.
npm run test:unit # Runs unit tests (vitest) npm run test:unit:watch # Opens vitest in watch mode npm run test:e2e # Runs e2e tests (cypress)
We have two test suites:
Most of the time, we recommend testing your code with Vitest. It's a much nicer experience, and it runs faster. That said, sometimes you need to test a full workflow from end-to-end, which is what Cypress is there for.
We use CrowdIn to handle translations, head on over to crowdin.com/project/kitsu-web to suggest changes or add new translations.
Translations use the ICU Message Syntax format. Read the syntax documentation.