Last week I wrote down the order to check things in when a project opens blank. The last section of that post was a list: four things that do not open yet, named but not explained. People wrote in about that list, so here it is properly.
One thing first, because it changes how you read the rest. None of these four is a feature we have not built. Each one is a place where some tool in the chain only recognises one spelling of a thing, and your repo uses the other one. That sounds like a small distinction. It is the difference between "this will never work" and "this breaks on a Tuesday for a reason you can see".
Each section below is the same four questions. What you see. Why it happens. What we do about it. What you can do today.
1. The requested module '...' does not provide an export named 'Button'
What you see. Nothing renders, and the error card says that sentence. Not a stack trace, not a component name — a module and a missing name. If the module is one of your own files, the card points at the import line in the file that wrote it, with a line and column you can click.
Why it happens. The package ships CommonJS only. It has no ES module entry at all.
A browser cannot import CommonJS. So a package like that reaches the canvas through the CDN's CommonJS-to-ESM conversion, and that conversion has to guess which names to export. It does it by reading the CommonJS source with a static lexer — a parser that looks for the shapes a build tool normally writes, exports.Button = ... and friends.
When a package assigns its API through a helper the lexer has not met, the lexer finds nothing. We measured one: @material-tailwind/react at 2.1.4, read with the same lexer the CDN itself uses, reports its exports as exactly ["__esModule"] — for the main entry and for every component subpath. The package has a Button. The lexer cannot see it, because the file says _export(exports, { Button: ... }) plus a hand-rolled star helper.
So import { Button } from '@material-tailwind/react' fails. And it fails at link time, before a single line of the module runs, which is why nothing renders rather than part of the page rendering. Linking is all-or-nothing.
Worth knowing: deep imports and ?bundle do not escape this. Both end at the same lexer.
What we do about it. The names do exist at runtime — they are properties on the module's default object, which is the CommonJS module.exports the conversion handed over. So we rewrite the file that does the importing:
// yours import { Button, ThemeProvider } from '@material-tailwind/react'; // what runs import __cui_cjs_0 from '@material-tailwind/react'; const { Button, ThemeProvider } = __cui_cjs_0; Two decisions in there that matter more than the rewrite itself.
It rewrites your importing file, not the package URL. There is a URL-level trick available — ask the CDN for named exports with a query parameter — and it is a trap. The parameter varies with whichever names a given file happens to use. So two files importing the same package get two different URLs. Two URLs means two module instances, which means a provider in one of them and its consumer in the other, looking at different contexts. Nothing says "the theme provider is right there and the component still cannot see it" quite like that. Rewriting the importer leaves the URL alone, so the package stays one instance.
And it only fires when the package's own manifest says there is no ES module entry. Not on a hunch, not from a list of package names we maintain. If we have not read the manifest, we do nothing. A rewrite fired on a guess is worse than the error it replaces, and we have the scar to prove it: a framework package we serve ourselves once got caught by this gate, and the "fix" broke a module that had been working.
What you can do. Mostly nothing, and that is the point. The case we deliberately leave alone is export * from 'some-cjs-package' — a star re-export has no list of names in it, so there is nothing to bind, and rewriting it would mean inventing names. If one of your barrel files does that, name the exports you actually use and it links.
The other lever is the import map in Project Settings: point the package at a build that ships ESM, if one exists. Many packages publish both and resolve to the CommonJS one by default.
2. require is not defined
What you see. The app renders, or part of it does, and then one view dies with that message. The card names the file and the line. Open the line and you find something like this:
<img src={require("assets/img/pattern_react.png").default} alt="" /> Why it happens. That is webpack. Create React App compiles that call into a module whose .default is the final asset URL. It is the standard way to reference an image in that era of React project. And it sits directly in the markup, so there is no import at the top of the file to warn you.
A browser module has no require. There is nothing to call. The line throws when the component renders, which is why you get a half-drawn page and not a blank one.
What we do about it. We rewrite it. The ES module spelling of the same idea is an import, and the canvas already serves project assets as modules: ask for a .png and you get a module whose default export is the URL.
So each distinct asset require in a file is hoisted into a real import at the top, and the binding is put where the call was. The .default is consumed along with the call — leaving it behind would read .default off a URL string and get undefined, which is the same bug with the error message removed. Nothing special resolves these: they go through the ordinary import pipeline, aliases and all, exactly as if you had written the import by hand. One Creative Tim view we tested on had eleven of them.
Two of the six templates on our Showcases page are from that era — material-dashboard-react and horizon-ui-chakra are both Create React App projects, with src/index.js entries. They open. This rewrite is most of the reason.
What you can do. The narrowing is worth knowing, because it tells you which failures are still yours. We only rewrite require of an asset — image, font, stylesheet, the file types the runtime already classifies. require('some-package') is left exactly where it is.
That is deliberate. An asset import cannot fail to link, so hoisting it is free. But turning a conditional require('some-package') into a top-level import would load that package unconditionally, in every render, including the branch that was never meant to reach it. That trade buys one working view and risks a working app. So if your require is of a package, or the path is computed at runtime, you will see this message and the fix is one line in your file.
3. The shell renders. Every route is empty.
This one has no error message, which makes it the most confusing of the four. Nothing is thrown. The layout appears — sidebar, header, the frame of the thing — and the content area is blank.
Why it happens. Your router is a generation behind the one we render.
React Router v5 described routes with <Switch> and component=. v6 and after describe them with <Routes> and element=. These are not two spellings of one API; they are different components with different props. Code written for v5 and rendered against the current generation produces a router that matches nothing, which is not an error — an empty match is a legal outcome. So you get a frame and no page.
What we do about it. Two things, and the first one happens before you even open the project.
The manifest check reads your package.json when you join a repo and says so up front: this project uses react-router-dom v5, whose routes are written with <Switch> and component=, so route-level pages may come up empty. It is a sentence, not a refusal — you still open the project, because plenty of it will render and you came to look at it. But you find out from a sentence instead of from a blank panel.
At render time there is the Smart Wrapper suggestion in the error card, which can put a router context around a file you opened on its own. That is worth separating from the version problem, because they look similar and are not the same thing:
- You opened
pages/dashboard.jsxdirectly, and it callsuseNavigateor reads the location. It needs a router above it, which the running app had and your direct open does not. One click puts one back. This works regardless of generation. - Your route definitions are v5. No wrapper fixes that. The wrapper provides routing context; it does not translate
component=intoelement=.
One detail from that wrapper, since this is the engineering post: the router we wrap with is the component router, not the data router. A data router installs its own error boundary. It catches a page's render error and paints React Router's error screen inside the canvas, so the error never reaches our card. You get a polite "unexpected error" panel instead of a file name and a line number. The component router gives the same routing context and lets errors propagate to the thing that can tell you where they came from.
What you can do. Open the page component directly rather than the route tree. You lose the navigation, you keep the page, and for looking at a UI that is usually the trade you wanted. If you need the real routes, upgrading the router is a real migration and we are not going to pretend otherwise.
4. A file your toolchain and ours read differently
What you see. A syntax error on a line your editor is perfectly happy with. Often with a character in it that looks harmless — the one we keep hitting is a bare & in JSX text, in a heading like Billing & Invoices.
Why it happens. Two parsers, same bytes, different answers. JSX has edge cases that are genuinely ambiguous, dialects that are configured rather than detected, and syntax proposals that one toolchain enables and another does not. Your build works because your build's parser was configured for your project, by you, possibly years ago.
What we do about it. Less than for the other three, honestly, and the shape of what we do is worth saying.
The manifest check catches the declared case: if your package.json configures a dialect our parser does not promise to agree about — a Flow preset, for instance — you get told before you open, in the same sentence-not-a-refusal way.
The undeclared case cannot be caught that way, because it needs the file's bytes and a disagreement that only shows up once something tries to read them. So it lands at render time, where the card names the file and the line. That is the whole mechanism. We cannot predict the disagreement; we can only make it cheap to find. Hence the clickable line number, and the report link that carries the details with it.
What you can do. Report it. I know how that reads. But this is the one category where a single report changes behaviour for everyone who hits the same construct, because the fix is in our parser handling and not in your project. The bare & got handled because somebody sent it.
And the fifth category, which is the biggest
Four causes is not the set of all reasons a stranger's repo might not render. It is the set of reasons we have met often enough to name.
That is why the manifest check warns and never blocks. A list of four that refused to open anything it did not recognise would reject projects that render fine, and it would be confidently wrong in exactly the cases nobody has reported yet. A warning that turns out to be unnecessary costs you one sentence. A refusal that turns out to be unnecessary costs you the project.
So: your repo may fail for a fifth reason. The card will still tell you which file and which line, the copy is still complete, the tree and the editor still work. A blank canvas is not an empty project.
If you are here because something of yours did not open
Go through the checklist first. It is the "what do I do now" version of this post, in the order things actually go wrong. Two of its five steps cover most blank screens in about ten seconds.
If you want to see what a working one looks like from the other side, open a template — no install, nothing to clone. And the note at the bottom of Community Templates says what gets through today, which is a shorter list than we would like and a longer one than it was.
None of these four is "unsupported". Each is a place where something in the chain only recognises one spelling. That is a much better problem to have, because spellings can be learned — but only the ones somebody tells us about.
