Want to contribute to Sitecore Content SDK? There are a few things you need to know.

Pre-requisites:

• node.js (Use an Active LTS version (cmd node -v to test)).
• npm (>= 9) installed (cmd npm -v to test).

Install yarn globally:

npm i -g yarn

Developing

See Branching overview below - We use dev for our current development.

1. Fork this repository to your own GitHub account and then clone it to your local device.
2. Create a new branch e.g. git switch -c feature/my-content-sdk-feature
3. When you're happy with your changes, open a Pull Request targeting the dev branch of the sitecore/content-sdk repository. You may add the Sitecore Content SDK Dev Reviewers group as Reviewers for potentially expedited initial PR review.
4. Note: CI will run lint for all packages, as well as tests for all packages. Please make sure these pass or your PR can not be merged.

Setting up

In your fork from the root of the monorepo:

• yarn install - this will install Lerna at the root, packages and will link them and allow the remaining scripts to be called.
• (optional) yarn install-git-hooks - installs a pre-push hook that will lint all packages before a git-push. Opt out per-push with the --no-verify flag.
• yarn build - will build all Sitecore Content SDK packages.

In our terms workspace - it's a sample or package.

• yarn workspaces focus <workspace> -> will install dependencies, linked dependencies for specified workspace.
• yarn workspaces foreach -Rt --from '<workspace>' run <command> -> will run <command> script for specified workspace including linked dependencies.

Working on a package

yarn workspaces focus
yarn workspaces foreach -Rt run build

Working on a sample

yarn workspaces focus
yarn workspaces foreach -Rt --no-private run build

• yarn reset - will clean all node_modules, re-install dependencies and link them, and then build all Sitecore Content SDK packages.

Developing sample

For the creation of the samples we are using initializers approach.

• initializer - the process for handling the creation of the appropriate template. See initializers.
• template - the sample populated by ejs tokens. See templates. Templates can be for e.g. nextjs.

If you want to use create-content-sdk-app from your local repository, run:

cd ./packages/create-content-sdk-app
npm i -g

To start developing the sample you have to do next:

• Copy watch.json.example file and name it watch.json. You have to set up appropriate arguments for the sample which you want to start to develop. Monorepo symlinking will work if you specify a destination under the source root samples directory (i.e. <root>\samples\<my-app>).
• Run yarn watch. A new sample will be created in the specified destination path. You can modify any file related to your sample under src/templates folder, and changed files will be automatically copied into your sample.

Linting and Code Style guidelines

The monorepo includes a top level .eslintrc file that each package inherits. In order to avoid linting errors and adhere to our style guidelines while developing, it is strongly recommended to install the vs code extension ESLint, and use it as the document formatter. Formatting the document with this plugin will fix formatting issues and avoid linting errors.

To lint manually, the following commands are available from the root of the monorepo, you may also install the git-hook which will run these commands as a pre-push hook:

yarn lint-packages // lint everything under ./packages
yarn lint-apps // lint everything under ./samples

You may also lint a package by itself by running yarn lint while the cwd is the root of the package, for example:

cd ./packages/core
yarn lint

Some linting errors may be fixed automatically using the --fix flag. You may do this from the root, however you will need -- twice before the flag in order to pass the argument to the inner command

yarn lint-packages -- -- --fix

In addition to linting rules, there are a few coding guidelines worth mentioning here that will cause less friction when trying to get a PR merged.

• TypeScript: make sure everything has the appropriate type.

• JSDoc: new functions, interfaces, classes, etc. need to have a JSDoc style comment above their declaration. Example: https://jsdoc.app/howto-es2015-classes.html

Run unit tests

To keep everything running smoothly, please include unit tests when applicable. To run all tests, from the root of the monorepo:

yarn test-packages

In the root of a package:

yarn test

API surface verification

The project uses API Extractor to track and verify the public API surface of all packages. This ensures that breaking changes to public APIs are caught before merging.

When API surface verification is required

API surface verification runs automatically in Github Actions for all pull requests. You'll need to update the API surface files if you add, remove, or modify public exports (classes, functions, interfaces, types).

Verifying API surface locally

Before pushing your changes, verify the API surface matches the existing report in the api/ folder.

From the root of the monorepo

yarn api-extractor:verify

This checks all packages and will fail if there are mismatches.

Updating API surface files

If you've intentionally changed the public API, update the API surface files:

From the root of the monorepo (updates all packages)

yarn api-extractor

From a specific package directory

cd packages/<package-name>
npm run api-extractor

This will:

1. Build the package
2. Generate a new API report in the temp/ folder
3. Compare it with the existing report in the api/ folder. If there are differences, copy the new report to api/

Important: Always review the generated API reports (packages/*/api/*.api.md) to ensure they reflect your intended changes. Commit these updated files along with your code changes.

Troubleshooting

Problem: Build of package or sample fails with the following error: cannot find module ...

Solution: If dependencies in a package change, you may need to install said dependencies. From the root of the monorepo:

yarn install

yarn install will solve the problem in most cases, however in nuclear scenarios you may run the following to completely reset the monorepo:

yarn reset

Branching overview

• dev- latest changes for the next release
• release - all major released versions