>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3588786. --> Reported by: [ajv009](https://www.drupal.org/user/3653917) >>> <h3 id="summary-problem-motivation">Problem/Motivation</h3> <p>The Canvas runtime has no <code>@/components/*</code> path alias in its import map, so any Canvas component that tries to import another Canvas component produces a silent runtime failure &mdash; the component renders blank with no error thrown. The same trap applies to relative CSS imports (<code>import './index.css'</code>), which also fail silently in Canvas runtime.</p> <p>This trap is easy to fall into because the imports work perfectly in Storybook (where Vite handles path aliases) and produce no error in the browser console. An agent building a composite component (e.g. an events listing that uses an event card sub-component) will write <code>import EventCard from '@/components/event_card'</code>, test it in Storybook where it renders correctly, upload it, and then be confused when the live site renders nothing. The root cause &mdash; a missing import map entry &mdash; is non-obvious and took multiple sessions to identify. It was independently encountered in both an efi-ed Q1 session and a jamie-demo session.</p> <p>Additionally, components downloaded via <code>canvas:download</code> can lose their <code>import './index.css'</code> statement. In one recorded case, <code>grid_container/index.jsx</code> pulled via <code>canvas download</code> was missing <code>import './index.css'</code>, silently breaking grid alignment across every component that used GridContainer.</p> <p>Root cause: Canvas's component runtime uses ES module import maps that only include npm package imports: <code>react</code>, <code>drupal-canvas</code>, <code>swr</code>, and a small set of platform packages. Vite path aliases like <code>@/components/*</code> are resolved at build time in the local Storybook/dev environment but Canvas does not replicate these aliases in its runtime import map. When a component is uploaded and executed in the Canvas runtime, any <code>@/components/*</code> import silently fails &mdash; the module cannot be found but no error is thrown because Canvas catches module resolution failures and renders nothing. Relative CSS imports (<code>import './index.css'</code>) are similarly unresolved in the Canvas bundle environment.</p> <h4 id="summary-steps-reproduce">Steps to reproduce</h4> <ol> <li>Build a Canvas component that imports a sub-component: <code>import EventCard from '@/components/event_card'</code>.</li> <li>Verify in Storybook &mdash; it renders correctly.</li> <li>Upload via <code>canvas:upload</code>.</li> <li>View on the live Acquia Source site.</li> <li>Observe: the component renders nothing. No browser-console error.</li> <li>Inspect the Canvas runtime import map: it covers <code>react</code>, <code>drupal-canvas</code>, <code>swr</code> only &mdash; no <code>@/components/*</code>.</li> </ol> <h3 id="summary-proposed-resolution">Proposed resolution</h3> <p>Document the constraint in <code>.claude/agents/component-builder.md</code>, the <code>component-authoring</code> skill, and <code>docs/migration/gotchas.md</code>. The fix at the component level is "always inline sub-component JSX" &mdash; there is no platform-level remediation proposed.</p> <p><strong>Step 1 &mdash; Add a "CANVAS RUNTIME HARD RULES" block to <code>.claude/agents/component-builder.md</code></strong> with two rules under "Import/Module resolution":</p> <pre>RULE: NEVER import from @/components/* Canvas runtime has no @/components path alias in its import map. If you need a sub-component pattern, INLINE the sub-component JSX directly into the consuming component file. Do not create a separate file for it. RULE: NEVER use `import './index.css'` Canvas does not support relative CSS file imports. All custom styles must go into global.css or use Tailwind utility classes.</pre><p><strong>Step 2 &mdash; Add a post-download lint step</strong> to the <code>canvas:download</code> workflow note: "After running <code>canvas:download</code>, scan all downloaded JSX files for <code>index.css</code> sibling files missing a corresponding <code>import './index.css'</code> statement &mdash; Canvas may have omitted it. Check whether the CSS is needed; if so, migrate the rules to <code>global.css</code>."</p> <p><strong>Step 3 &mdash; Add a one-line entry to <code>docs/migration/gotchas.md</code>:</strong> "Canvas runtime has no <code>@/components/*</code> import map &mdash; inline sub-component JSX. No <code>import './index.css'</code> &mdash; put styles in <code>global.css</code>. See component-builder.md &sect; Canvas Runtime Hard Rules."</p> <p><strong>Step 4 &mdash; Mirror the rules</strong> in <code>.claude/skills/component-authoring/SKILL.md</code> (or equivalent) under "Canvas component self-containment".</p> <h3 id="summary-remaining-tasks">Remaining tasks</h3> <ul> <li>Add the Canvas Runtime Hard Rules block to <code>.claude/agents/component-builder.md</code>.</li> <li>Add the same rules to <code>.claude/skills/component-authoring/SKILL.md</code> (confirm canonical filename).</li> <li>Add the gotchas.md entry.</li> <li>Add the post-download lint step note (or, optionally, implement as <code>scripts/post-download-lint.mjs</code> &mdash; see open question).</li> <li>Verify: <code>grep -n "@/components" .claude/agents/component-builder.md</code> returns the NEVER rule.</li> <li>Verify: <code>grep -n "index.css" .claude/agents/component-builder.md</code> returns the NEVER rule.</li> </ul> <h3 id="summary-ui-changes">User interface changes</h3> <p>None directly. Indirectly: components that follow the inline pattern will render on Acquia Source instead of blank.</p> <h3 id="summary-api-changes">API changes</h3> <p>None at the platform level. The constraint is documented as a hard rule for component authors &mdash; Canvas's import map shape is the Acquia platform decision.</p> <h3 id="summary-data-model-changes">Data model changes</h3> <p>None. New documentation only &mdash; agent file rule block and gotchas.md entry.</p> <h3 id="summary-internal-references">Internal references</h3> <ul> <li>Source markdown: <code>RESEARCH-2026-04-28/99-final/ISSUES/Sprint-5-Drupal-Canvas-Gotchas/02-P1-7-canvas-component-cannot-import-canvas-component.md</code> (id: P1-7)</li> <li>Gotcha catalog: <code>RESEARCH-2026-04-28/07-cross-cutting/acquia-cms-gotchas.md</code> &sect; G13 (verbatim entry on path alias import failure)</li> <li>Consolidated issues: <code>RESEARCH-2026-04-28/99-final/consolidated-issues.md</code> &sect; P1-7</li> <li>Q1 discovery: <code>RESEARCH-2026-04-28/03-efi-ed-source/Q1-records-1-to-2884/issues-found.md</code> Bug 1</li> <li>jamie-demo independent re-discovery: <code>RESEARCH-2026-04-28/06-jamie-demo-old/95q5i-77cf5bb9-half1/issues-found.md</code> I7</li> <li>canvas:download CSS import omission: <code>RESEARCH-2026-04-28/02-edu-site-mockup-ai/dbc7a979/issues-found.md</code> HIGH-1</li> <li>Relative CSS import failure: <code>RESEARCH-2026-04-28/02-edu-site-mockup-ai/fc6fc3db/issues-found.md</code> ISSUE-3</li> <li>Recommended verbatim text: <code>RESEARCH-2026-04-28/99-final/migrate-site-skill-recommendations.md</code> &sect; component-builder.md / Canvas Self-Containment Hard Rules</li> </ul> <h3 id="summary-open-questions">Open questions</h3> <ul> <li>Is there a separate <code>canvas-authoring</code> skill SKILL.md in addition to <code>component-builder.md</code>? If yes, both files need the rule. Check <code>.claude/skills/</code> for the canonical list.</li> <li>The <code>canvas:download</code> lint step would ideally be a script (<code>scripts/post-download-lint.mjs</code>). Is the user open to creating that script now, or should it stay as a text instruction in the agent file?</li> </ul>