Loading and Troubleshooting

How the core loads features

A broken feature cannot bring the application down:

1. The server validates each feature.yml. A feature that breaks the schema is left out with an error in the server log and never reaches the browser.
2. At startup, the browser goes through appData.features. If the sdk: is not compatible, the feature is skipped.
3. It adds the CSS <link>s and imports the entry with import(). All features load in parallel.
4. It calls register(sdk) with the calls queued. If it finishes in less than 5 seconds, they are applied (loaded); if it throws, failed; if it takes longer, timeout. In the last two cases its CSS and calls are removed, and the sdk becomes inert (later calls are ignored with a warning).
5. The router waits for the loading to finish (5 seconds at most) before painting the first page.
6. Afterwards the feature callbacks (permission functions, item functions, pages, components) run guarded: an error is logged once in the console and does not break the menu or the header.

Diagnostics

In the server log, the feature.yml problems, once per server process:

Feature hello-react: feature.yml frontend.entry dist/index.js not found in public/ (not built?), frontend not loaded
Feature hello-react: public/dist/style.css exists but is not declared in feature.yml frontend.css, so it is not loaded

In the browser console:

__CLARIVE_SDK__.version      // '1.0.0'
__CLARIVE_SDK__.features     // [{ id, entry, css, sdk, status: 'loaded'|'failed'|'timeout'|'skipped', ms, error?, cssErrors? }]

A summary is logged when loading ends: [features] 1 loaded or [features] 1 loaded, 1 failed (foo).

To find the content of a feature in the DOM use div.cla-feature[data-feature="<id>"]. A plain [data-feature="<id>"] also finds the (empty) <link> in the <head>.

Common errors

Symptom	Cause	Fix
The feature is not in __CLARIVE_SDK__.features	The directory starts with #, there is no frontend in feature.yml, or feature.yml breaks the schema	Check the server log: it says what is wrong
Feature <id>: feature.yml ... not found in public/ (not built?) in the log	The feature has not been built or entry is wrong	npm run build; check frontend.entry (relative to public/)
Feature <id>: feature.yml frontend.sdk is required in the log	feature.yml has no sdk	Add sdk: "^1"
"xxx" is not shared by the SDK...	A library that is not in the import map is imported without bundling it	Remove it from external so it gets bundled
entry not found or not loadable at ...	The entry cannot be imported	npm run build and reload
default export must be a register(sdk) function	The entry does not default-export register	export default function register(sdk) {...}
status: 'skipped', requires SDK ^1.2	The feature requires a newer SDK than the core has	Lower sdk: or upgrade Clarive
status: 'timeout'	import() + register() take more than 5 seconds	Lighter entry, no backend calls in register
TypeError: [features] <id>: ... at startup	Malformed sdk call in register	Read the message: it says what is missing
React is not defined	A file with JSX without import React	Add import React from 'react'
Failing hooks / "Invalid hook call"	Another React was bundled	react/react-dom must be in external
The page has no styles	frontend.css not declared (the server log warns about it)	Declare css: dist/style.css
Styles do not apply to a Modal/Dropdown	Popups are painted outside the wrapper	Use className/wrapClassName/getPopupContainer
useSdk() must be used inside a feature page or component	useSdk() outside a feature page or component (e.g. in register)	In register use the sdk parameter
The endpoint returns 403	The user's role lacks the action	Grant the action; use sdk.can() to hide the button beforehand
The endpoint returns a JSON 404	The namespace does not match the id, or the server was not restarted	Check namespace => 'feature/<id>/api' and restart the server
The topic still shows the core view of a revision	The repository CI does not declare viewer_components, the server was not restarted or the topic view is cached	Look for [features] component ... not available (reason) in the console; restart and run cla db-cache_clear
A section captures the routes of another	Section urls that are a prefix of another (/hello and /hello-react)	Rename one (the core warns in the console)

SDK versioning

The SDK follows semantic versioning, and frontend.sdk in feature.yml says which versions a feature works with:

• Minor (1.0 to 1.1): things are added. Existing features keep working. A feature that uses something added in a minor declares it: sdk: "^1.1".
• Major (1.x to 2.0): something in the contract breaks (removing a method, a CSS variable or a shared library, or a new major of React or antd). Features with sdk: "^1..." are skipped until they are updated.

The contract is: the sdk object and @clarive/sdk, the shared libraries, the props of the core screens that accept components, the --cla-* CSS variables and the feature.yml schema.

History: 1.0 is the first release, with everything described in these pages.