This is the lerna-managed monorepo for the blocks that make up the Arc Themes. This monorepo is a collection of packages for blocks. Blocks are tagged together.
Builds the storybook static site to the default storybook-static directory based on documentation. This command is exclusively used for building the storybook static site for Chromatic. Chromatic is used for visual regression testing within your pull request. The GitHub Workflow can be modified depending on potential Chromatic or Storybook updates.
Run prettier to format all files not excluded by .prettierignore. The .prettierrc.js opts into using tabs for accessibility. See Prettier docs for more information on tabs in prettier. Prettier is run on pre-commit using lint-staged for changed files. npx lint-staged is called from the Husky pre-commit file. The pre-commit hook ensures that all of the files don't need to be formatted with each iteration. I'd also encourage downloading and using the recommended VS Code extensions configured, specifically the Prettier - Code formatter extension.
The command will generate a new chain. This will create a new block folder with a chain folder containing the new chain. The prompt is available: _templates/chain/new.
The command will generate a new content source. This will create a new block folder with a content source folder containing the new sources folder. The prompt is available: _templates/content-source/new.
The command will generate a new feature. This will create a new block folder with a feature folder containing the new feature. The prompt is available: _templates/feature/new.
The command will generate a new feature within an existing feature block. Within the existing feature folder, a new feature will be created within the preexisting block. The prompt is available: _templates/feature/feature.
The command will generate a new content source within an existing feature block. Within the existing feature folder, a new content source will be created within the preexisting block. The prompt is available: _templates/feature/content-source.
The command will generate a new content source within an existing content source block. Within the existing content source folder, a new content source will be created within the preexisting block. The prompt is available: _templates/content-source/content-source.
The command will generate a new feature within an existing content source block. Within the existing content source folder, a new feature will be created within the preexisting block. The prompt is available: _templates/content-source/feature.
Install all dependencies, including nested ones. See more on local paths. The local paths are used for fusion linking. On postinstall, the npx lerna clean -y will run, which removes nested dependencies docs. Any dependencies that an individual block needs, it needs to be installed at the top-level for testing to work. For example, the package algoliasearch will need to be installed at the top-level for testing to work for the algolia-assortment-content-source-block. It should also be installed in the nested block's package.json for installing on Fusion.
Based off of the Lokalise structure, this generates locale files that Fusion can read for each block (e.g., Article Body Block's intl.json). The base translations are available within the locale folder. This script is also located within the locale folder. Note that there is a block that is exclusively translations across other blocks called Global Phrases Block.
The base lint command that runs eslint on all .js and .jsx files in blocks and .storybook directory, excluding any files in .eslintignore. ESlint is used to find potential issues in code. Using VS Code, you can install the ESLint extension to see lint issues in the editor.
Fixes any lint issues that can be automatically fixed from the files mentioned in npm run lint.
The base lint command that runs stylelint on .scss files, excluding any files in .stylelintignore. Stylelint is used to find potential issues in styles.
Fixes any stylelint issues that can be fixed automatically from the files mentioned in npm run lint:styles.
Similar to npm run test:changed-feature-branch, this runs on pre-push and within the GitHub Workflow. It will run eslint on all code that have changed since origin/main. See the .eslintignore and the .eslintrc.js for the configuration.
Using npm run lint:changed-feature-branch logic, but will also fix any potential problems using ESlint's --fix flag. Note that there are some errors and warnings that cannot be fixed automatically, so this command will not fix all issues.
See storybook setup below for more information. This is a helpful way of developing blocks without using Fusion. Please note the pattern used in blocks for consuming content in the .storybook/alias/content.js file. This is a helpful way of mocking content for blocks using mocks available in the storybook/mock-content folder. There is also a pattern of mocking the content call by using presentational components with a thin wrapper. See examples at Large Promo and its Storybook file, as well as using a parent class-based component with Alert Bar and its Storybook file.
Run all tests for code that has changed. Will also show coverage for changed code. This is the command to run when developing. To see coverage thresholds goals, see the jest.config.js file coverageThreshold property. For more information on the jest configuration coverage, see jest docs.
Runs tests for all blocks that have changed since origin/main. This runs in the GitHub Workflow for testing blocks on Pull Requests. It also runs on pre-push using Husky. Note that the Husky pre-push file is located in root and not in the package.json, per version 7 of Husky.
- Make sure you have an npmrc file with read-access to @wpmedia packages. This is available in your dev settings.
- Create an
.npmrcfile in the root of your project.
@wpmedia:registry=https://npm.pkg.github.com/
registry=https://registry.npmjs.org
//npm.pkg.github.com/:_authToken=ghp_secrettoken
npm ito install packagesnpm run storybookto show the blocks in Storybook. For more info on Storybook, see their documentation. In confluence, we have Storybook best practices as well for themes.
This repo uses trunk-based development. All work is merged into main, and the themesVersion field in the root package.json determines which themes release version blocks are published under.
Every merge to main that changes block code (.js, .jsx, .json, .scss) triggers the publish workflow. It reads themesVersion from package.json and publishes all changed blocks to GitHub Packages under the dist-tag arc-themes-release-version-<themesVersion>.
No manual steps are needed — just merge your PR and blocks are published.
When you're ready to start a new themes release (e.g., moving from 4.1.0 to 4.2.0):
- Create a PR that changes
themesVersioninpackage.jsonfrom"4.1.0"to"4.2.0" - Merge the PR into
main - The publish workflow will automatically:
- Tag the previous version's final commit as
themes-v4.1.0 - Begin publishing blocks under
arc-themes-release-version-4.2.0
- Tag the previous version's final commit as
That's it. The git tag provides a permanent record of exactly which commit was the last publish for each version, and can be used to view history or create hotfix branches later.
# View what shipped in a specific version
git log themes-v4.0.0..themes-v4.1.0
# View what's been published in the current version so far
git log themes-v4.1.0..mainHotfixes are for the rare case when you need to patch a version you've already moved past. A dedicated hotfix workflow handles publishing.
-
Find the tag for the version you need to fix:
git tag -l "themes-v*" -
Create a hotfix branch from that tag:
git checkout -b hotfix/4.1.0 themes-v4.1.0
-
Make your fix, commit, and push:
git push -u origin hotfix/4.1.0
-
The hotfix workflow runs automatically and publishes the fix under the original dist-tag (
arc-themes-release-version-4.1.0).
Note: Hotfix branches are not merged back into
main. If the fix is also needed onmain, cherry-pick it into a separate PR targetingmain.
Please see the release notes in Confluence if you are a Themes developer.
Blocks are published with dist-tags in the format arc-themes-release-version-X.Y.Z, corresponding to the themesVersion in package.json at the time of publish. These are used in the Theme Manifest repo.
Shield:
This work is licensed under a Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International License
