Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Rename RAZZLE_TESTING_ADDONS environment variables #3067

Merged
merged 14 commits into from Feb 16, 2022
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
@@ -6,6 +6,7 @@

- Markup change in `LinkView` component.
- Rename `core-sandbox` to `coresandbox` for sake of consistency @sneridagh
- Extend the original intent and rename `RAZZLE_TESTING_ADDONS` to `ADDONS`. @sneridagh
See https://docs.voltocms.com/upgrade-guide/ for more information.

### Feature
@@ -184,3 +184,53 @@ describe('Addon chain loading dependencies', () => {
]);
});
});

describe('Addon via env var - Released addon', () => {
const originalEnv = process.env;

beforeEach(() => {
jest.resetModules();
process.env = {
...originalEnv,
ADDONS: 'test-released-via-addons-env-var',
};
});

afterEach(() => {
process.env = originalEnv;
});

it('addons can be specified on the fly using ADDONS env var - Released addon', () => {
const base = path.join(__dirname, 'fixtures', 'test-volto-project');
const reg = new AddonConfigurationRegistry(base);
expect(
Object.keys(reg.packages).includes('test-released-via-addons-env-var'),
).toBe(true);
});
});

describe('Addon via env var - local packages folder addon', () => {
const originalEnv = process.env;

beforeEach(() => {
jest.resetModules();
process.env = {
...originalEnv,
ADDONS: 'test-local-packages-via-addons-env-var',
};
});

afterEach(() => {
process.env = originalEnv;
});

it('addons can be specified on the fly using ADDONS env var - local packages folder addon', () => {
const base = path.join(__dirname, 'fixtures', 'test-volto-project');
const reg = new AddonConfigurationRegistry(base);
expect(
Object.keys(reg.packages).includes(
'test-local-packages-via-addons-env-var',
),
).toBe(true);
});
});

Some generated files are not rendered by default. Learn more.

Some generated files are not rendered by default. Learn more.

@@ -0,0 +1,4 @@
{
"name": "test-local-packages-via-addons-env-var",
"main": "src/index.js"
}
@@ -0,0 +1 @@
export default (config) => config;
@@ -124,7 +124,7 @@ class AddonConfigurationRegistry {

this.initDevelopmentPackages();
this.initPublishedPackages();
this.initTestingPackages();
this.initAddonsFromEnvVar();

this.dependencyGraph = buildDependencyGraph(
this.resultantMergedAddons,
@@ -203,15 +203,16 @@ class AddonConfigurationRegistry {
}
}

initTestingPackages() {
if (process.env.RAZZLE_TESTING_ADDONS) {
process.env.RAZZLE_TESTING_ADDONS.split(',').forEach(
this.initTestingPackage.bind(this),
initAddonsFromEnvVar() {
if (process.env.ADDONS) {
process.env.ADDONS.split(',').forEach(
this.initAddonFromEnvVar.bind(this),
);
}
}

initTestingPackage(name) {
initAddonFromEnvVar(name) {
// First lookup in the packages folder, local to the root (either vanilla Volto or project)
const normalizedAddonName = name.split(':')[0];
const testingPackagePath = `${this.projectRootPath}/packages/${normalizedAddonName}/src`;
if (fs.existsSync(testingPackagePath)) {
@@ -233,6 +234,10 @@ class AddonConfigurationRegistry {
this.packages[normalizedAddonName] || {},
pkg,
);
} else {
// Fallback in case the addon is released (not in packages folder nor in development, but in node_modules)
const normalizedAddonName = name.split(':')[0];
this.initPublishedPackage(normalizedAddonName);
}
}

@@ -385,14 +390,14 @@ class AddonConfigurationRegistry {
}

/**
* Allow testing packages addons to customize Volto and other addons.
* Allow packages from addons set in env vars to customize Volto and other addons.
*
* Same as the above one, but specific for Volto testing addons
* Same as the above one, but specific for Volto addons coming from env vars
*/
getTestingAddonCustomizationPaths() {
getAddonsFromEnvVarCustomizationPaths() {
let aliases = {};
if (process.env.RAZZLE_TESTING_ADDONS) {
process.env.RAZZLE_TESTING_ADDONS.split(',').forEach((addon) => {
if (process.env.ADDONS) {
process.env.ADDONS.split(',').forEach((addon) => {
const normalizedAddonName = addon.split(':')[0];
const testingPackagePath = `${this.projectRootPath}/packages/${normalizedAddonName}/src`;
if (fs.existsSync(testingPackagePath)) {
@@ -89,3 +89,77 @@ It displays the errors of the non-compliant customizations (in server console) i
#### Internationalization errors (i18n)

It will enable the log of missing i18n messages (in console).

## Use add-ons via the `ADDONS` environment variable

You can use the `ADDONS` environment variable to enable and configure add-ons in your project.

When running your app, the add-ons will be loaded in the following order:

- the file `package.json`
- programmatically set in the file `volto.config.js`
- the environment variable `ADDONS`

In the environment variable `ADDONS`, you can specify:

- released (or published) packages that were installed previously in your environment and are already present in the `node_modules` directory,
- or addons located in the `packages` folder of your project, such as Volto's testing packages.

`ADDONS` can be used to temporarily add an add-on to your build for testing purposes.

```bash
yarn add volto-slate
ADDONS=volto-slate:asDefault yarn start
```

`ADDONS` can also be used to temporarily enable a feature or a set of customizations.

```bash
# given a folder './packages/coresandbox', like in vanilla Volto
ADDONS=coresandbox:multilingualFixture yarn start
```

You can specify multiple add-ons, seperated by commas:

```bash
ADDONS=test-addon,test-addon2 yarn start
```

You can specify profiles for installation:

```bash
ADDONS=test-addon:profile1,test-addon2:profile2 yarn start
```

The following code snippets demonstrate how to configure add-ons.
First in `package.json`:

```json
"addons": [
"@kitconcept/volto-blocks-grid"
]
```

...next in `volto.config.js`:

```js
module.exports = {
addons: ['@eeacms/volto-accordion-block']
}
```

...and finally using `ADDONS`:

```bash
yarn add volto-slate
ADDONS=volto-slate:asDefault yarn start
```

As a result, your app will load the add-ons in the following order:

- `@kitconcept/volto-blocks-grid`
- `@eeacms/volto-accordion-block`
- `volto-slate`

!!! important
`ADDONS` does *not* work for development packages, which are *always* enabled if defined in your `jsconfig.json` or via `mrs.developer.json`.
@@ -22,11 +22,16 @@ environment variable.

This is specially useful in CI while developing add-ons, so you can pass an specific configuration that deals with the addon config properly.

## Add addons for testing purposes
## Add add-ons via environment variable for testing purposes

Quite often, you need different configurations and enabling components for testing purposes. You can use the `RAZZLE_TESTING_ADDONS` environment variable to define them. These addons do not have the capacity to install dependencies (as opposed to properly defined addons), but all the rest of the addon features work as expected.
Sometimes you need to enable different configurations and enable optional components (for example, testing purposes).
You can use the `ADDONS` environment variable to define them.

RAZZLE_TESTING_ADDONS=test-addon,test-addon2 yarn start
```bash
ADDONS=test-addon,test-addon2 yarn start
```

See [Add-ons via environment variables](../configuration/environmentvariables.md) for more information.

## Developing Cypress tests

@@ -43,6 +43,15 @@ The `LinkView` component `The link address is:` part now it's wrapped in a `<p>`

Only applying to Volto core development, for the sake of consistency with the other fixtures, `core-sandbox` fixture it's been renamed to `coresandbox` in all scripts and related file paths and filenames.

### Extend the original intent and rename `RAZZLE_TESTING_ADDONS` to `ADDONS`.

Originally the `RAZZLE_TESTING_ADDONS` environment variable was an escape hatch to load some components and configurations not present in vanilla Volto.
One could enable them at will.
Initially thought as fixtures for acceptance tests, the original intent has been repurposed and extended to just `ADDONS`.
One could extend the `ADDONS` list configuration via this environment variable.

It works for published packages, such as those add-ons that live in the `packages` folder locally to your project.
This is similar to the testing add-ons from vanilla Volto.

## Upgrading to Volto 14.x.x

@@ -70,11 +70,11 @@
"ci:start-api-plone-workingCopy": "make test-acceptance-server-workingcopy",
"ci:start-api-guillotina": "make test-acceptance-guillotina",
"ci:start-frontend": "RAZZLE_API_PATH=http://localhost:55001/plone yarn build && start-test start:prod http://localhost:3000 cypress:run",
"ci:start-frontend-coresandbox": "RAZZLE_TESTING_ADDONS=coresandbox RAZZLE_API_PATH=http://localhost:55001/plone yarn build && start-test start:prod http://localhost:3000 cypress:run:coresandbox",
"ci:start-frontend-multilingual": "RAZZLE_TESTING_ADDONS=coresandbox:multilingualFixture RAZZLE_API_PATH=http://localhost:55001/plone yarn build && start-test start:prod http://localhost:3000 cypress:run:multilingual",
"ci:start-frontend-workingCopy": "RAZZLE_TESTING_ADDONS=coresandbox:workingCopyFixture RAZZLE_API_PATH=http://localhost:55001/plone yarn build && start-test start:prod http://localhost:3000 cypress:run:workingCopy",
"ci:start-frontend-coresandbox": "ADDONS=coresandbox RAZZLE_API_PATH=http://localhost:55001/plone yarn build && start-test start:prod http://localhost:3000 cypress:run:coresandbox",
"ci:start-frontend-multilingual": "ADDONS=coresandbox:multilingualFixture RAZZLE_API_PATH=http://localhost:55001/plone yarn build && start-test start:prod http://localhost:3000 cypress:run:multilingual",
"ci:start-frontend-workingCopy": "ADDONS=coresandbox:workingCopyFixture RAZZLE_API_PATH=http://localhost:55001/plone yarn build && start-test start:prod http://localhost:3000 cypress:run:workingCopy",
"ci:start-project-frontend": "cd my-volto-app && RAZZLE_API_PATH=http://localhost:55001/plone yarn build && start-test start:prod http://localhost:3000 'cd .. && yarn cypress:run'",
"ci:start-frontend-guillotina": "RAZZLE_TESTING_ADDONS=volto-guillotina RAZZLE_API_PATH=http://localhost:8081/db/web RAZZLE_LEGACY_TRAVERSE=true yarn build && start-test start:prod http://localhost:3000 cypress:run:guillotina",
"ci:start-frontend-guillotina": "ADDONS=volto-guillotina RAZZLE_API_PATH=http://localhost:8081/db/web RAZZLE_LEGACY_TRAVERSE=true yarn build && start-test start:prod http://localhost:3000 cypress:run:guillotina",
"ci:cypress:run": "start-test ci:start-api-plone http-get://localhost:55001/plone ci:start-frontend",
"ci:cypress:project:run": "start-test ci:start-api-plone http-get://localhost:55001/plone ci:start-project-frontend",
"ci:cypress:run:coresandbox": "start-test ci:start-api-plone-coresandbox http-get://localhost:55001/plone ci:start-frontend-coresandbox",
@@ -181,13 +181,13 @@ const defaultModify = ({
// Disabling the ESlint pre loader
config.module.rules.splice(0, 1);

let testingAddons = [];
if (process.env.RAZZLE_TESTING_ADDONS) {
testingAddons = process.env.RAZZLE_TESTING_ADDONS.split(',');
let addonsFromEnvVar = [];
if (process.env.ADDONS) {
addonsFromEnvVar = process.env.ADDONS.split(',');
}

const addonsLoaderPath = createAddonsLoader(
[...registry.getAddonDependencies(), ...testingAddons],
[...registry.getAddonDependencies(), ...addonsFromEnvVar],
registry.packages,
);

@@ -197,8 +197,8 @@ const defaultModify = ({
];

config.resolve.alias = {
...registry.getTestingAddonCustomizationPaths(),
...registry.getAddonCustomizationPaths(),
...registry.getAddonsFromEnvVarCustomizationPaths(),
...registry.getProjectCustomizationPaths(),
...config.resolve.alias,
'../../theme.config$': `${projectRootPath}/theme/theme.config`,
@@ -237,8 +237,8 @@ const defaultModify = ({
addonsAsExternals = registry.addonNames.map((addon) => new RegExp(addon));
}

if (process.env.RAZZLE_TESTING_ADDONS) {
testingAddons.forEach((addon) => {
if (process.env.ADDONS) {
addonsFromEnvVar.forEach((addon) => {
const normalizedAddonName = addon.split(':')[0];
const p = fs.realpathSync(
registry.packages[normalizedAddonName].modulePath,