diff --git a/docs/.vitepress/config.js b/docs/.vitepress/config.js index 9548db24b..38d491e6d 100644 --- a/docs/.vitepress/config.js +++ b/docs/.vitepress/config.js @@ -35,6 +35,7 @@ const sidebar = [ { text: "Accessibility statement", link: "/accessibility" }, { text: "Micropub clients", link: "/clients" }, { text: "Supported specifications", link: "/specifications" }, + { text: "Local development", link: "/development" }, ], }, ]; diff --git a/docs/contributing.md b/docs/contributing.md index 6633665eb..2c41b8c63 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -32,7 +32,7 @@ We use GitHub issues to track bugs. Browse [existing reports](https://github.com ## Submit a fix -If you spot something broken and can supply a fix, [fork the project](https://github.com/getindiekit/indiekit/fork) and create a pull request. See [setting up a local development environment](#setting-up-a-local-development-environment) to get started. +If you spot something broken and can supply a fix, [fork the project](https://github.com/getindiekit/indiekit/fork) and create a pull request. See [Setting up a local development environment](development.md) to get started. Commit messages for fixes should be prefixed with `fix:`, for example: @@ -62,119 +62,4 @@ You can use [Indiekit’s plug-in API](plugins/api/index.md) to add (or prototyp When publishing a plug-in to the npm registry, add the `indiekit-plugin` keyword to help other Indiekit users find it. To have a plug-in listed [in the plug-in directory](https://getindiekit.com/plugins/), submit a pull request against the relevant page in the documentation. -## Setting up a local development environment - -### Project structure - -This project uses a monorepo structure, with concerns split into separate Node modules located in the `/packages` folder: - -| Module{width=200px} | Purpose | -| :----- | :------ | -| `indiekit` | Coordinating functions and the Express web server. | -| `frontend` | Frontend component library, used for the application interface. | -| `error` | Error handling for the core module and plug-ins. | -| `create-indiekit` | Project initialiser, used when running `npm create indiekit`. | -| `endpoint-*` | Application endpoint plug-ins. | -| `post-type-*` | Post type plug-ins. | -| `preset-*` | Publication preset plug-ins. | -| `store-*` | Content store plug-ins. | -| `syndicator-*` | Syndicator plug-ins. | - -Helper functions used in tests are in the `/helpers` folder. - -### Project architecture - -Indiekit uses the [Express server framework](https://expressjs.com). - -Configuration defaults get merged with any user-defined values (Indiekit uses [cosmiconfig](https://github.com/cosmiconfig/cosmiconfig) to find and load a configuration object). - -Plug-ins listed under the `plugins` array are then loaded and interrogated for known API methods, which further update the configuration. - -Express waits for a resolved configuration file before starting the server. - -### Running locally - -To run the server locally, first install its dependencies: - -```sh -npm install -``` - -The provided configuration file allows some options to be assigned using environment variables. - -Create an `.env` file in the root of the project, for example: - -```sh -# Required -PUBLICATION_URL="https://example.com" - -# Database connection string URI (optional) -MONGO_URL="mongodb://127.0.0.1:27017" - -# Test saving files to a content store on GitHub (optional) -GITHUB_USER="username" -GITHUB_REPO="indiekit-test" -GITHUB_BRANCH="main" -GITHUB_TOKEN="12345abcde" - -# Test syndicating content to a Mastodon server (optional) -MASTODON_URL="https://example.social" -MASTODON_USER="indiekit-test" -MASTODON_ACCESS_TOKEN="12345abcde" -``` - -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 -``` - -To enable authentication, use the `production` flag: - -```sh -npm run dev --production -``` - -### Tests - -The project uses both unit and integration tests. Run tests using the following command: - -```sh -npm test -``` - -To run an individual test, use `node` followed by the path to the test. For example: - -```sh -node packages/indiekit/test/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 test:coverage -``` - -### Linting - -Consistent and high-quality code is maintained using [Prettier](https://prettier.io) with [ESLint](https://eslint.org) used to check JavaScript files and [Stylelint](https://stylelint.io) used to check CSS stylesheets. - -You can check that any changes use the preferred code style by running the following command: - -```sh -npm run lint -``` - -You automatically fix any issues by running the following command: - -```sh -npm run lint:fix -``` +See also [Setting up a local development environment](development.md). diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 000000000..6e7c891d5 --- /dev/null +++ b/docs/development.md @@ -0,0 +1,116 @@ +# Setting up a local development environment + +## Project structure + +This project uses a monorepo structure, with concerns split into separate Node modules located in the `/packages` folder: + +| Module{width=200px} | Purpose | +| :----- | :------ | +| `indiekit` | Coordinating functions and the Express web server. | +| `frontend` | Frontend component library, used for the application interface. | +| `error` | Error handling for the core module and plug-ins. | +| `create-indiekit` | Project initialiser, used when running `npm create indiekit`. | +| `endpoint-*` | Application endpoint plug-ins. | +| `post-type-*` | Post type plug-ins. | +| `preset-*` | Publication preset plug-ins. | +| `store-*` | Content store plug-ins. | +| `syndicator-*` | Syndicator plug-ins. | + +Helper functions used in tests are in the `/helpers` folder. + +## Project architecture + +Indiekit uses the [Express server framework](https://expressjs.com). + +Configuration defaults get merged with any user-defined values (Indiekit uses [cosmiconfig](https://github.com/cosmiconfig/cosmiconfig) to find and load a configuration object). + +Plug-ins listed under the `plugins` array are then loaded and interrogated for known API methods, which further update the configuration. + +Express waits for a resolved configuration file before starting the server. + +## Running locally + +To run the server locally, first install its dependencies: + +```sh +npm install +``` + +The provided configuration file allows some options to be assigned using environment variables. + +Create an `.env` file in the root of the project, for example: + +```sh +# Required +PUBLICATION_URL="https://example.com" + +# Database connection string URI (optional) +MONGO_URL="mongodb://127.0.0.1:27017" + +# Test saving files to a content store on GitHub (optional) +GITHUB_USER="username" +GITHUB_REPO="indiekit-test" +GITHUB_BRANCH="main" +GITHUB_TOKEN="12345abcde" + +# Test syndicating content to a Mastodon server (optional) +MASTODON_URL="https://example.social" +MASTODON_USER="indiekit-test" +MASTODON_ACCESS_TOKEN="12345abcde" +``` + +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 +``` + +To enable authentication, use the `production` flag: + +```sh +npm run dev --production +``` + +## Tests + +The project uses both unit and integration tests. Run tests using the following command: + +```sh +npm test +``` + +To run an individual test, use `node` followed by the path to the test. For example: + +```sh +node packages/indiekit/test/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 test:coverage +``` + +## Linting + +Consistent and high-quality code is maintained using [Prettier](https://prettier.io) with [ESLint](https://eslint.org) used to check JavaScript files and [Stylelint](https://stylelint.io) used to check CSS stylesheets. + +You can check that any changes use the preferred code style by running the following command: + +```sh +npm run lint +``` + +You automatically fix any issues by running the following command: + +```sh +npm run lint:fix +```