BETA NOTICE: Widget Builder is currently in active beta. Features, APIs, and interface elements may evolve as we refine developer tooling.Access is available on staging environments for testing, and select customers have approved early access in production.For the latest updates or to request beta access, contact your Customer Success Manager (CSM) or Account Executive.
Widget Builder is a powerful tool that enables you to create custom widgets and fragments, tweak UI elements, and build experiences that match your brand and vision.
1. You can break your site with invalid code
Widget Builder gives you a lot of freedom. While liberating, this freedom also means you can write code that doesn’t work or causes unforeseen consequences.
- One misplaced curly brace, a missing import, or an undefined variable can crash parts of your site or cause unexpected behavior.
- Unlike a WYSIWYG editor, this is real code. If something breaks, it’s not always as simple as clicking “Undo.”
- You may need to understand console errors, browser stack traces, or version history to fix it.
IMPORTANT: Always test new or modified widgets/fragments on a staging site before committing to production. Invalid code can break layouts globally.
2. Copy-pasting from the Internet? Proceed with caution
Find a cool snippet on Stack Overflow or a slick React component from someone's blog? While it's tempting to just drop it in, it's always advised to slow down and thoroughly review it first. Use online examples as learning references, not production code.
As you can imagine, not all code on the internet is safe.
- Some of it’s outdated, assumes a different environment, or worse — introduces security risks (like unsafe DOM manipulation, poor input handling, or third-party scripts you don’t control).
- If you don’t fully understand the code you’re copying, it’s like adding a stranger’s key to your front door.
3. Custom code can introduce security vulnerabilities
React helps protect you from many common web vulnerabilities — like cross-site scripting (XSS) — by escaping content automatically. But that protection disappears if you manually bypass React’s safety mechanisms.
Avoid or use extreme caution with the following APIs:
API | Why it’s dangerous |
|---|
dangerouslySetInnerHTML
| Injects raw HTML directly into the DOM. If it includes user-supplied data, it can enable XSS attacks. |
eval()
| Executes arbitrary strings as JavaScript — almost never necessary and highly unsafe. |
innerHTML
| Bypasses React’s built-in sanitization and can insert untrusted markup or scripts. |
What to do instead
- Stick to React best practices: keep everything declarative.
- Avoid raw HTML injection: If you must use HTML from an external source, sanitize it thoroughly.
- Be cautious with third-party code: Use well-known libraries and verify their safety.
- Test in isolation: Experiment in a staging environment before updating your live community.
4. Workflow and version control
Beyond secure coding, how you work in Widget Builder can make or break your site’s stability.
Save often, commit thoughtfully
- Use Save frequently while developing to avoid losing work.
- Treat Commits as mini releases — each one immediately updates every layout using that widget/fragment.
- Write meaningful Commit Messages (e.g., “Added moderator badge logic to Post List Item fragment”) to keep an "audit trail" of changes.
Use staging environments
- Always test widgets/fragments on staging before deploying to production.
- Validate layout behavior, data rendering, and performance with real preview data.
Communicate with admins
- If other team members manage layouts, notify them before publishing commits — changes propagate site-wide.
Use naming conventions
Consistent names make fragments and widgets/fragments easy to find and maintain.For example:
- Post List Item – Compact
- Banner CTA – Spring Promo
- Search Bar – Minimal
5. Performance and maintainability tips
Small code choices can have a big impact on performance and long-term maintainability.
Do
- Use the Utils Library for safe, platform-aware access to data, navigation, and permissions.
- Use React Query (
useQuery, useMutation) for efficient data fetching and caching. - Keep your components modular and focused — one component per responsibility.
- Scope CSS carefully — styles are already isolated within the Shadow DOM.
Avoid
- Heavy synchronous operations (e.g., large data processing in
render). - Direct DOM manipulation (
document.querySelector, etc.); rely on React state instead. - Excessive inline styles or logic inside JSX; move reusable logic to helpers.
TL;DR
- Editing code fragments is powerful, but not without risk. If you’re unsure about a piece of code, pause and double-check — ask questions, run a quick test, or review with another developer.
- Taking time to validate your work can save hours of debugging — and keep your site safe, fast, and stable.
- Never feed untrusted HTML into
dangerouslySetInnerHTML.