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

[7.x] [kbn/optimizer] only build specified themes (#70389) #70671

Merged
merged 1 commit into from
Jul 3, 2020
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
[kbn/optimizer] only build specified themes (#70389)
Co-authored-by: spalger <[email protected]>
Co-authored-by: Elastic Machine <[email protected]>
Co-authored-by: cchaos <[email protected]>
# Conflicts:
#	packages/kbn-optimizer/src/integration_tests/__snapshots__/basic_optimization.test.ts.snap
  • Loading branch information
Spencer authored and spalger committed Jul 2, 2020
commit 23e203cc74695f355aa34e8f09f30b1332b1c442
8 changes: 4 additions & 4 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -425,7 +425,7 @@ We are still to develop a proper process to accept any contributed translations.

When writing a new component, create a sibling SASS file of the same name and import directly into the JS/TS component file. Doing so ensures the styles are never separated or lost on import and allows for better modularization (smaller individual plugin asset footprint).

Any JavaScript (or TypeScript) file that imports SASS (.scss) files will automatically build with the [EUI](https://elastic.github.io/eui/#/guidelines/sass) & Kibana invisibles (SASS variables, mixins, functions) from the [`styling_constants.scss` file](https://github.com/elastic/kibana/blob/master/src/legacy/ui/public/styles/_styling_constants.scss). However, any Legacy (file path includes `/legacy`) files will not.
All SASS (.scss) files will automatically build with the [EUI](https://elastic.github.io/eui/#/guidelines/sass) & Kibana invisibles (SASS variables, mixins, functions) from the [`globals_[theme].scss` file](src/legacy/ui/public/styles/_globals_v7light.scss).

**Example:**

@@ -668,15 +668,15 @@ Part of this process only applies to maintainers, since it requires access to Gi
Kibana publishes [Release Notes](https://www.elastic.co/guide/en/kibana/current/release-notes.html) for major and minor releases. The Release Notes summarize what the PRs accomplish in language that is meaningful to users. To generate the Release Notes, the team runs a script against this repo to collect the merged PRs against the release.

#### Create the Release Notes text
The text that appears in the Release Notes is pulled directly from your PR title, or a single paragraph of text that you specify in the PR description.
The text that appears in the Release Notes is pulled directly from your PR title, or a single paragraph of text that you specify in the PR description.

To use a single paragraph of text, enter `Release note:` or a `## Release note` header in the PR description, followed by your text. For example, refer to this [PR](https://github.com/elastic/kibana/pull/65796) that uses the `## Release note` header.

When you create the Release Notes text, use the following best practices:
* Use present tense.
* Use present tense.
* Use sentence case.
* When you create a feature PR, start with `Adds`.
* When you create an enhancement PR, start with `Improves`.
* When you create an enhancement PR, start with `Improves`.
* When you create a bug fix PR, start with `Fixes`.
* When you create a deprecation PR, start with `Deprecates`.

20 changes: 20 additions & 0 deletions packages/kbn-optimizer/README.md
Original file line number Diff line number Diff line change
@@ -42,6 +42,26 @@ When a directory is listed in the "extraPublicDirs" it will always be included i

Any import in a bundle which resolves into another bundles "context" directory, ie `src/plugins/*`, must map explicitly to a "public dir" exported by that plugin. If the resolved import is not in the list of public dirs an error will be thrown and the optimizer will fail to build that bundle until the error is fixed.

## Themes

SASS imports in bundles are automatically converted to CSS for one or more themes. In development we build the `v7light` and `v7dark` themes by default to improve build performance. When producing distributable bundles the default shifts to `*` so that the distributable bundles will include all themes, preventing the bundles from needing to be rebuilt when users change the active theme in Kibana's advanced settings.

To customize the themes that are built for development you can specify the `KBN_OPTIMIZER_THEMES` environment variable to one or more theme tags, or use `*` to build styles for all themes. Unfortunately building more than one theme significantly impacts build performance, so try to be strategic about which themes you build.

Currently supported theme tags: `v7light`, `v7dark`, `v8light`, `v8dark`

Examples:
```sh
# start Kibana with only a single theme
KBN_OPTIMIZER_THEMES=v7light yarn start

# start Kibana with dark themes for version 7 and 8
KBN_OPTIMIZER_THEMES=v7dark,v8dark yarn start

# start Kibana with all the themes
KBN_OPTIMIZER_THEMES=* yarn start
```

## API

To run the optimizer from code, you can import the [`OptimizerConfig`][OptimizerConfig] class and [`runOptimizer`][Optimizer] function. Create an [`OptimizerConfig`][OptimizerConfig] instance by calling it's static `create()` method with some options, then pass it to the [`runOptimizer`][Optimizer] function. `runOptimizer()` returns an observable of update objects, which are summaries of the optimizer state plus an optional `event` property which describes the internal events occuring and may be of use. You can use the [`logOptimizerState()`][LogOptimizerState] helper to write the relevant bits of state to a tooling log or checkout it's implementation to see how the internal events like [`WorkerStdio`][ObserveWorker] and [`WorkerStarted`][ObserveWorker] are used.
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
$globalStyleConstant: 11;
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
$globalStyleConstant: 12;
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
$globalStyleConstant: 13;
1 change: 1 addition & 0 deletions packages/kbn-optimizer/src/common/index.ts
Original file line number Diff line number Diff line change
@@ -29,3 +29,4 @@ export * from './array_helpers';
export * from './event_stream_helpers';
export * from './disallowed_syntax_plugin';
export * from './parse_path';
export * from './theme_tags';
92 changes: 92 additions & 0 deletions packages/kbn-optimizer/src/common/theme_tags.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
/*
* Licensed to Elasticsearch B.V. under one or more contributor
* license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright
* ownership. Elasticsearch B.V. licenses this file to you under
* the Apache License, Version 2.0 (the "License"); you may
* not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/

import { parseThemeTags } from './theme_tags';

it('returns default tags when passed undefined', () => {
expect(parseThemeTags()).toMatchInlineSnapshot(`
Array [
"v7dark",
"v7light",
]
`);
});

it('returns all tags when passed *', () => {
expect(parseThemeTags('*')).toMatchInlineSnapshot(`
Array [
"v7dark",
"v7light",
"v8dark",
"v8light",
]
`);
});

it('returns specific tag when passed a single value', () => {
expect(parseThemeTags('v8light')).toMatchInlineSnapshot(`
Array [
"v8light",
]
`);
});

it('returns specific tags when passed a comma separated list', () => {
expect(parseThemeTags('v8light, v7dark,v7light')).toMatchInlineSnapshot(`
Array [
"v7dark",
"v7light",
"v8light",
]
`);
});

it('returns specific tags when passed an array', () => {
expect(parseThemeTags(['v8light', 'v7light'])).toMatchInlineSnapshot(`
Array [
"v7light",
"v8light",
]
`);
});

it('throws when an invalid tag is in the array', () => {
expect(() => parseThemeTags(['v8light', 'v7light', 'bar'])).toThrowErrorMatchingInlineSnapshot(
`"Invalid theme tags [bar], options: [v7dark, v7light, v8dark, v8light]"`
);
});

it('throws when an invalid tags in comma separated list', () => {
expect(() => parseThemeTags('v8light ,v7light,bar,box ')).toThrowErrorMatchingInlineSnapshot(
`"Invalid theme tags [bar, box], options: [v7dark, v7light, v8dark, v8light]"`
);
});

it('returns tags in alphabetical order', () => {
const tags = parseThemeTags(['v7light', 'v8light']);
expect(tags).toEqual(tags.slice().sort((a, b) => a.localeCompare(b)));
});

it('returns an immutable array', () => {
expect(() => {
const tags = parseThemeTags('v8light');
// @ts-expect-error
tags.push('foo');
}).toThrowErrorMatchingInlineSnapshot(`"Cannot add property 1, object is not extensible"`);
});
65 changes: 65 additions & 0 deletions packages/kbn-optimizer/src/common/theme_tags.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
/*
* Licensed to Elasticsearch B.V. under one or more contributor
* license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright
* ownership. Elasticsearch B.V. licenses this file to you under
* the Apache License, Version 2.0 (the "License"); you may
* not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/

import { ascending } from './array_helpers';

const tags = (...themeTags: string[]) =>
Object.freeze(themeTags.sort(ascending((tag) => tag)) as ThemeTag[]);

const validTag = (tag: any): tag is ThemeTag => ALL_THEMES.includes(tag);
const isArrayOfStrings = (input: unknown): input is string[] =>
Array.isArray(input) && input.every((v) => typeof v === 'string');

export type ThemeTags = readonly ThemeTag[];
export type ThemeTag = 'v7light' | 'v7dark' | 'v8light' | 'v8dark';
export const DEFAULT_THEMES = tags('v7light', 'v7dark');
export const ALL_THEMES = tags('v7light', 'v7dark', 'v8light', 'v8dark');

export function parseThemeTags(input?: any): ThemeTags {
if (!input) {
return DEFAULT_THEMES;
}

if (input === '*') {
return ALL_THEMES;
}

if (typeof input === 'string') {
input = input.split(',').map((tag) => tag.trim());
}

if (!isArrayOfStrings(input)) {
throw new Error(`Invalid theme tags, must be an array of strings`);
}

if (!input.length) {
throw new Error(
`Invalid theme tags, you must specify at least one of [${ALL_THEMES.join(', ')}]`
);
}

const invalidTags = input.filter((t) => !validTag(t));
if (invalidTags.length) {
throw new Error(
`Invalid theme tags [${invalidTags.join(', ')}], options: [${ALL_THEMES.join(', ')}]`
);
}

return tags(...input);
}
5 changes: 5 additions & 0 deletions packages/kbn-optimizer/src/common/worker_config.ts
Original file line number Diff line number Diff line change
@@ -20,11 +20,13 @@
import Path from 'path';

import { UnknownVals } from './ts_helpers';
import { ThemeTags, parseThemeTags } from './theme_tags';

export interface WorkerConfig {
readonly repoRoot: string;
readonly watch: boolean;
readonly dist: boolean;
readonly themeTags: ThemeTags;
readonly cache: boolean;
readonly profileWebpack: boolean;
readonly browserslistEnv: string;
@@ -80,6 +82,8 @@ export function parseWorkerConfig(json: string): WorkerConfig {
throw new Error('`browserslistEnv` must be a string');
}

const themes = parseThemeTags(parsed.themeTags);

return {
repoRoot,
cache,
@@ -88,6 +92,7 @@ export function parseWorkerConfig(json: string): WorkerConfig {
profileWebpack,
optimizerCacheKey,
browserslistEnv,
themeTags: themes,
};
} catch (error) {
throw new Error(`unable to parse worker config: ${error.message}`);
Loading