Knowledge Base

TODO this is the beginning of a potential knowledge base.

Design System Publisher

You may have some issues with Design System Publisher. Here are some common ones and suggestions on how to troubleshoot them.

Bug reports and feature requests can be submitted at the Design System Publisher GitHub repository.

Browser Doesn't Match Filesystem Content

To speed up the start process, the Design System Publisher caches some resources, internally. Sometimes, caches tend to get out of sync and need cleaning. Run the following command to flush the internal caches and restart the development server to see if it fixes the issue:

npm run dspublisher:clean

The issue may also concern the browser’s cache. In case the above doesn’t help, try cleaning the browser’s cache, as well.

Page Heading Changes Not Rendered

There’s one caveat about the page headings. On a regular page, if you change the main heading in the AsciiDoc (i.e., = Page Heading), you’ll see the heading update as expected. But if you use layout: tabbed-page in the page front matter, the tabbed page heading is actually retrieved from the front matter’s title field. Therefore, you may want to change that instead.

Application Won't Start on Linux

When the application won’t start on Linux, make sure that the necessary dependencies are installed by running the following at the command-line:

sudo apt install build-essential autoconf automake libtool pkg-config libpng-dev nasm zlib1g-dev

Development Server Fails to Start

The npm run dspublisher:start script, which starts up the development server, has certain expectations about your development environment. The development server may fail to start for one of the following reasons:

npm Ignoring Scripts

If you configure npm with ignore-scripts=true, the startup fails. An example error message for this is the following:

Error in "/Users/[username]/.npm/_npx/c089b35bd0e8ac07/node_modules/@vaadin/dspublish
er/node_modules/gatsby-transformer-sharp/gatsby-node.js":
Something went wrong installing the "sharp" module

Cannot find module '../build/Release/sharp-darwin-arm64v8.node'

Remove the ignore-scripts configuration and delete the /.npm/_npx from the home directory to fix the issue.

Missing Xcode Command Line Tools

On macOS, you need install the Xcode Command Line Tools. Otherwise you might receive the following type of error during start up:

dsp@[version]:start ████████████████████ Initializing
npx,concurrently,--kill-others,--raw,"npx @vaadin/dspublisher@[version] --develop","mvn -C" failed with code 1

Gatsby on Windows

Design System Publisher is based on Gatsby, which has known issues on Windows. If you’re using Windows, see Gatsby on Windows for more information.

It’s recommended to use Linux or macOS as your development platform. On Windows, you can use Windows Subsystem for Linux (WSL) to run Design System Publisher.

Licenses

You can contact [email protected] for further help.

I Get A Trial Message Although I Have A Valid License

Verify that you have a valid license by going to https://vaadin.com/pro/validate-license. If not, either your company’s license administrator hasn’t yet assigned a seat for you, or the license is no longer valid.

SSLHandshakeException with Multiplatform Runtime

This is a known error in SSLHandshakeException reported by users of WebSphere Liberty and WildFly in Docker. See the following discussion for more details: https://vaadin.com/forum/t/running-mpr-project-on-websphere-liberty-fails-with-suncertpathbuilderexcep/160675.

Docs