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
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
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'
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.
You can contact email@example.com 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/thread/18444677/running-mpr-project-on-websphere-liberty-fails-with-suncertpathbuilderexcep.