Skip to content
On this page

Contributing

Thanks for considering contributing to this project. Indiekit is still in the early stages of development, but you can help this project grow and improve by:

This project is intended to be a safe, welcoming space for collaboration with contributors expected to adhere to the project’s code of conduct.

Proposing a new feature

The motivation behind Indiekit is to build a tool that makes interacting with IndieWeb protocols and technologies accessible, adaptable and approachable. Indiekit also aims to be platform agnostic and built for the long term.

New features should be added with these principles in mind, and improvements that move the project closer to this goal are strongly encouraged.

We use GitHub issues to track feature proposals. Browse existing proposals before adding yours.

Reporting a bug

We use GitHub issues to track bugs. Browse existing reports before adding yours.

Submitting a fix

If you spot something that’s broken and can supply a fix, you can fork the project and create a pull request. See setting up a local development environment to get started.

Commit messages for fixes should be prefixed with fix:, for example:

fix: don’t throw error if a user is signed in

If a fix affects a specific module, include the name of the module in the commit message, for example:

fix(syndicator-twitter): only post replies to tweets

Improving the documentation

Indiekit’s documentation is designed to be accessible and approachable, but it can always be improved.

Documentation can be found in the /docs folder and is written using Markdown syntax. You can contribute changes using GitHub’s interface.

Commit messages for documentation updates should be prefixed with docs:, for example:

docs: fix typo in getting started instructions

Adding a localisation

Localisations are managed using Localazy. If you see a translation that is not quite right or would like to add a new language, create an account and contribute to the project.

Developing a plug-in

Often the best way to add (or prototype) a new feature is to develop a plug-in using Indiekit’s plug-in API.

When publishing a plug-in to the npm registry, add the indiekit-plugin tag so that other Indiekit users can find it. You can also request to have it listed alongside other plug-ins on the project’s website.

Setting up a local development environment

Project structure

This project uses a monorepo structure, with concerns split into separate npm modules located in the /packages folder:

ModulePurpose
packages/indiekitCore module. Provides coordinating functions and the Express web server.
packages/errorError handling for the core module and plug-ins.
packages/frontendFrontend component library, used for the application interface.
packages/endpoint-*Application endpoint plug-ins.
packages/preset-*Publication preset plug-ins.
packages/store-*Content store plug-ins.
packages/syndicator-*Syndicator plug-ins.

Helper functions used in tests are also split into modules. These are located in the /helpers folder.

Project architecture

Indiekit uses the Express server framework.

Configuration defaults are merged with any user-defined values (Indiekit uses cosmiconfig to find and load a configuration object).

Plug-ins listed in the configuration’s plugin array are then loaded and interrogated for known API methods, which in turn update the server’s configuration further.

Once the configuration has been fully resolved, these values are passed to the Express server before it can then start.

Running locally

To run the server locally, first install its dependencies:

sh
npm install

You can then start the server:

sh
npm start

To automatically restart the server whenever a file change is detected, use:

sh
npm run dev

Tests

AVA is used to run and manage tests, of which both unit and integration types are used.

The following environment variables need to be set before running tests:

  • TEST_PUBLICATION_URL
  • TEST_SESSION_SECRET
  • TEST_TOKEN
  • TEST_TOKEN_NO_SCOPE

TEST_TOKEN and TEST_TOKEN_NO_SCOPE provide IndieAuth access tokens whose me value matches that set in TEST_PUBLICATION_URL.

TEST_TOKEN should provide scope for create update delete and TEST_TOKEN_NO_SCOPE should provide no scope at all.

Homebrew Access Token is a useful tool for creating access tokens for this purpose.

Tests can be run using the following command:

sh
npm test

To run tests for an individual file, you can call AVA directly using the npx command. For example:

sh
npx ava packages/indiekit/tests/index.js

Test coverage

The project aims to achieve close to 100% test coverage. You can check code coverage by running the following command:

sh
npm run coverage

Linting

Prettier is used to maintain consistent and high-quality code. You can check that any changes use the preferred code style by running the following command:

sh
npm run lint