Sonar-ui-common NPM

Sonar-ui-common

Library containing all common components, helpers and types for both SonarQube and SonarCloud.

It is available on the npm registry: https://www.npmjs.com/package/sonar-ui-common

How to use

There is no index file so you have to import components with their path like this :

import BugIcon from 'sonar-ui-common/components/icons/BugIcon';

Initialize it

To use the library, it should first be initialized by these methods:

import Initializer from 'sonar-ui-common/helpers/init';

Initializer
  .setUrlContext('/sonarqube')  // [required] Provide the web context
  .setMessages({})              // [optional] Provide your l10n bundle, retrieved anyway you want (from ws call, localstorage, json file...)
  .setLocale('en')              // [optional] Provide the language of your l10n bundle
  .setReactDomContainer('#app');// [optional] Is a css selector of the DOM node where the React app is attached. Defaults to '#content'.

The urlContext MUST be set before using the library or it will throw an Error. The l10n data can be set asynchronously, i.e. messages and locale can stay undefined if they need to be updated later. The default messages contain only a default error message, and the default locale is 'en'. The reactDomContainerSelector is completely optional and defaults to #content for backward compatility, it won't display any warning or error if not initialized at all.

Ambient types

Ambients types are available in the types.d.ts, to benefit from them in your project you include it in your tsconfig.json file, example:

{
  "compilerOptions": {
    /*...*/
  },
  "include": ["./src/main/js/**/*", "node_modules/sonar-ui-common/types.d.ts"]
}

Run test that use Sonar-ui-common components

To ease testing your components that depends on Sonar-ui-common components you should initialize Sonar-ui-common in your test runner. Create a SetupSUC.ts file that you add in the setupFiles config of jest, with a similar content:

import ThemeContext from 'sonar-ui-common/components/theme';
import Initializer, { DEFAULT_LOCALE } from 'sonar-ui-common/helpers/init';
import theme from '../../src/app/theme';

Initializer.setLocale(DEFAULT_LOCALE).setMessages({}).setUrlContext('');

// Hack : override the default value of the context used for theme by emotion
// This allows tests to get the theme value without specifiying a theme provider
ThemeContext['_currentValue'] = theme;
ThemeContext['_currentValue2'] = theme;

Styled-components

While developing styled components, you should seriously consider adding one of those extension to your IDE : https://github.com/Microsoft/typescript-styled-plugin#usage

It will provide syntax highlighting, quick-fix and intellisense.

What to improve

Add a global index file
Expose sonar-ui-common from sonar-web to reduce bundle size from extensions, currently it's duplicated in every extensions. Also it should help with theming and allows us to remove most of the call to ThemeProvider. Our current way of using ThemeProvider everywhere is mostly due to the fact that every extension is loading a different ThemeProvider component (it means that this ThemeProvider is duplicated for each extension).
Better management of theming (currently all extensions needs to reference the theme file from sonar-web in their build)
CSS of component based on theme (we currently rely on the fact that all usage of sonar-ui-common also compile CSS of components with the correct CSS custom properties setup)
Add release button in burgr
Display failing jobs in burgr

Contribute

Checkout the project
yarn inside it
Before pushing do a yarn validate to check that everything is allright

Using `yarn link`

To make it easier when developping both on the lib and SonarQube or SonarCloud (or an extension), you can use the yarn link feature. To set it up:

Build sonar-ui-common with : yarn build
Then from inside the build/dist folder of sonar-ui-common do: yarn link (might require sudo access)
Inside SQ/SC folder do: yarn link sonar-ui-common
Now you current build of sonar-ui-common will be available locally in SQ/SC, if you change things in sonar-ui-common you'll need to rebuild it to see it in SQ/SC

It's also possible to link directly from the sources but you won't be able to build SQ/SC with gradle and you are not as close to the reality, so you might get more suprises when using the packaged version of sonar-ui-common.

There is also a few gotcha's that you can encounter when linking:

Running the sonar-web unit tests might not work as expected:
- It might see duplicated versions of react for various reasons
- Testing a component with mount that has a sonar-ui-common component that is implemented with hooks can fail
Same when runing sonar-web typescript checking

Validating that everything work with `sonar-web`

A good practice before publishing the package is to make sure everything work well with built version of SQ/SC using gradle. The best way to do that is to :

Run yarn package in sonar-ui-common
Run yarn add /path/to/the/generated/package/file.zip
Build with gradle from SQ/SC root folder: ./gradlew build -x test -x obfucsate

Publish new version

Automated way

It's possible to use the release script. There is one requirements though: globally install npmrc (npm install -g npmrc) to manage your .npmrc profiles. You will also need two profiles defined (check the package readme to know how to set them up):

One named npm that should target npm registry and that contain your npm auth token
And one named default that targets repox

If you meet those requirements you just need to call yarn release 0.0.x and the script will automatically:

stash your current changes
update the package.json and CHANGELOG.md files
package the module
create a release commit and tag it
switch your npmrc file to target npm and publish the package (you will still need to manually enter the new version and your two factor auth token when prompted by yarn)
push the commit and the tag
pop the stashed changes

Manual way

If everything is green, QG and travis jobs
Bump versions in package.json
yarn to update the yarn.lock file if needed
Update the changelog (leave the Unreleased part which will be filled for the next version)
Push and tag the release commit
yarn package to create the package to be published
yarn publish ./build/dist/sonar-ui-common-x.y.z.tgz to actually publish it to npm registry (you might want to check your .npmrc file to make sure you are not targeting repox)