Hi Plasmic community,
I wanted to share my experience setting up code components with app hosting in a Next.js codegen project. I encountered multiple issues that took about 5 hours to debug, and I’m hoping this comprehensive guide helps others avoid the same pain. I’ve solved most issues, with one remaining question at the end.
TL;DR - Critical Fixes
- Use
@plasmicapp/host@1.0.214- NOT latest (1.0.222) - Component names must be valid JavaScript identifiers - no spaces/hyphens
- Dark mode CSS will affect Plasmic artboards - needs CSS overrides
- Preview works only with valid component names
Issue 1: White Screen of Death 
SOLVED
Problem
When configuring app host URL, Plasmic Studio would go completely white with message “Looks like the host app is taking a while to load.”
Root Cause
Version conflicts between Plasmic Studio’s internal version (1.0.214) and the latest npm package (1.0.222).
Solution
npm install @plasmicapp/host@1.0.214 --save-exact
If you already installed a different version:
rm -rf node_modules package-lock.json
npm install @plasmicapp/host@1.0.214 --save-exact
npm install
Issue 2: Components Rendering as Black Boxes SOLVED
Problem
After adding app host, all existing components rendered as solid black rectangles. Console showed multiple “duplicate host version” errors like:
Encountered likely duplicate host version: 1.0.214 vs 1.0.222
Solution
Same as above - use version 1.0.214. The version mismatch causes rendering failures.
Issue 3: Preview Mode Breaking SOLVED
Problem
When wrapping elements with custom code components, preview mode fails with:
Error: Unexpected token, expected "," (71:14)
Root Cause
Component names with spaces or hyphens generate invalid JavaScript:
// This breaks:
import { My Component Name } from './component'
Solution
Use valid JavaScript identifiers for component names:
registerComponent(MyComponent, {
name: 'MyComponentName', // No spaces or hyphens!
displayName: 'My Component Name', // Spaces OK in display name
// ...
});
Issue 4: Black Artboard Backgrounds SOLVED
Problem
All artboards show black background even though they’re set to “transparent” in the UI. Only happens after connecting app host.
Root Cause
App host runs your Next.js app in iframes, so your global CSS applies. In my case, dark mode CSS was the culprit:
@media (prefers-color-scheme: dark) {
:root {
--background: #0a0a0a; /* This was making artboards black */
}
}
Solution
Add CSS overrides to force light mode in Plasmic contexts:
/* Force light mode for Plasmic Studio */
@media (prefers-color-scheme: dark) {
:root {
--background: #ffffff !important;
--foreground: #171717 !important;
}
html {
color-scheme: light !important;
}
}
Issue 5: Components Turn White/Lose Colors SOLVED
Problem
After fixing black backgrounds, all colored components turned white.
Solution
Be more specific with CSS selectors - only override background, not all colors:
/* Only target specific Plasmic elements */
[data-plasmic-canvas-envs] {
background: white !important;
}
[data-plasmic-canvas-envs] body {
background: white !important;
}
Complete Working Setup
1. Package Version
{
"dependencies": {
"@plasmicapp/host": "1.0.214"
}
}
2. App Host Page
// pages/plasmic-host.tsx
import * as React from 'react';
import { PlasmicCanvasHost, registerComponent } from '@plasmicapp/host';
import { MyComponent } from '../components/MyComponent';
registerComponent(MyComponent, {
name: 'MyComponentName', // No spaces/hyphens
displayName: 'My Component Name',
props: {
// ... your props
},
importPath: '@/components/MyComponent',
});
export default function PlasmicHost() {
return <PlasmicCanvasHost />;
}
3. Global CSS Fix
/* Prevent dark mode from affecting Plasmic */
@media (prefers-color-scheme: dark) {
:root {
--background: #ffffff !important;
--foreground: #171717 !important;
}
html {
color-scheme: light !important;
}
}
/* Plasmic-specific overrides */
[data-plasmic-canvas-envs] {
background: white !important;
}
[data-plasmic-canvas-envs] body {
background: white !important;
}
Key Learnings
- Version sensitivity is not documented - Plasmic Studio uses specific internal versions that must match
- App host runs your entire app context - Your CSS will affect Plasmic Studio’s rendering
- Each artboard is an iframe - Performance implications and CSS inheritance
- Component names must be valid JS - This affects preview generation
- Check browser console - Duplicate host version errors are the key diagnostic
Debugging Tips
- If white screen → version issue
- If black components → version issue or CSS conflict
- If preview fails → check component name validity
- If colors wrong → CSS selectors too broad
My Remaining Question 
How can I make artboards truly transparent instead of white?
I’ve tried:
[data-plasmic-canvas-envs] {
background: transparent !important;
}
But artboards still show white background. The UI says “transparent” but displays white. Is there a way to achieve actual transparency for artboards when using app host?
Hope this helps someone! Despite these issues, code components are powerful once you get past the setup hurdles. The 5+ hours of debugging were painful, but now it’s working well.
Environment:
- Next.js 13+ with Pages Router
- Plasmic Codegen (not loader)
- @plasmicapp/host@1.0.214
- Vercel deployment
Feel free to ask if you need more details about any of these solutions!
