Limiting exports from content.config.ts

[psncl]

📚 Subject area/topic

Content Collection configuration

📋 Page(s) affected (or suggested, for new content)

https://docs.astro.build/en/guides/content-collections/#defining-collections

📋 Description of content that is out-of-date or incorrect

Recently, I faced an issue related to adding cloudflare adapter for SSR, which I think I narrowed down to exporting something other than the content collection from src/content.config.ts.

I use the astro-paper theme for a site. That theme's content collection config file exports a string const in addition to the actual collections.

export const BLOG_PATH = "src/data/blog";

This const is then imported in another utility file called getPath.ts.

When I added cloudflare adapter to my project, pnpm build started giving an error related to getPath:

14:16:02 [build] Rearranging server assets...
14:16:02 [ERROR] [@astrojs/cloudflare] An unhandled error occurred while running the "astro:build:done" hook
ENOENT: no such file or directory, open 'D:\astro-paper-cloudflare\dist\_worker.js\chunks\getPath_BImV0riY.mjs'
  Stack trace:
    at async open (node:internal/fs/promises:641:25)
    at async Object.afterBuildCompleted (file:///D:/astro-paper-cloudflare/node_modules/.pnpm/@astrojs+cloudflare@12.6.10_80423d8ba74735b2c16b97c9f0caed57/node_modules/@astrojs/cloudflare/dist/utils/cloudflare-module-loader.js:128:26)
    at async withTakingALongTimeMsg (file:///D:/astro-paper-cloudflare/node_modules/.pnpm/astro@5.12.0_jiti@2.4.2_lig_6af3358a8afa341e0e945f6f2fdd3368/node_modules/astro/dist/integrations/hooks.js:32:12)
    at async runHookBuildDone (file:///D:/astro-paper-cloudflare/node_modules/.pnpm/astro@5.12.0_jiti@2.4.2_lig_6af3358a8afa341e0e945f6f2fdd3368/node_modules/astro/dist/integrations/hooks.js:456:5)
    at async AstroBuilder.run (file:///D:/astro-paper-cloudflare/node_modules/.pnpm/astro@5.12.0_jiti@2.4.2_lig_6af3358a8afa341e0e945f6f2fdd3368/node_modules/astro/dist/core/build/index.js:185:7)
 ELIFECYCLE  Command failed with exit code 1.

After a day of trying other things, I ultimately figured out that BLOG_PATH variable that was imported from content.config.ts was the culprit. It got fixed when I moved that export to another file.

---

Now, I'm not fully certain why Astro doesn't like content.config.ts having that export. According to Claude, the issue might be:

When you were importing `BLOG_PATH` from `content.config.ts`, you created a dependency chain that the Cloudflare adapter couldn't handle properly:

getPath.ts → imports → content.config.ts
content.config.ts → uses astro:content (special Astro module)

The problem is:

1. content.config.ts is a special file - It's processed by Astro's content layer system and uses astro:content which has special build-time behavior
2. The Cloudflare adapter bundles differently - It needs to create a Worker bundle that runs in Cloudflare's environment
3. Circular/complex dependencies with content config - When getPath.ts imports from content.config.ts, and that config file is used during content collection processing, it can create a bundling issue where the module graph gets confused

---

Provided that it's true that you shouldn't export other things from that file, I asked on Discord whether this is potentially something that should be in the docs. I was suggested to create an issue here so it can be clarified.

🖥️ Reproduction

Here is a commit that fixes this issue in a fork of the astro-paper repo.

psncl/astro-paper-cloudflare@9baca03

[sarah11918]

Hi, thanks for adding the issue!

I'm not sure that this is something that needs adding to our docs. We do in this section both define this .ts file as a special file with a special purpose, and immediately following saying that it's special, we list out an example with numbered items of what this file must contain. In particular, it does say "export a single collections object to register your content collections."

So, I think with all that, we've been pretty clear about what the purpose and structure of this file must be? I was thinking, "I guess we can mention it's a special file" but we already do that. In docs, it's important not to get too involved saying what doesn't work (because, lots of things don't work! You could go on forever! Where do you draw the line?!) but focus on documenting exactly what does and how something should be. And I think we've done that here?

Happy for anyone to add their thoughts here, but my instinct is this isn't something to be added to the documentation.

[psncl]

Yes, I agree that it already saying export a single collections object does drive the point home.

Could there be some other 'solution' to this? Through adding tests or linting? A test that fails if the export from this file is anything other than a single collections object? I don't know if that's standard software engineering practice.

[sarah11918]

If there were something like that, it's no longer a documentation issue! I believe when researching this behaviour with the devs, they seemed to think that the actual behaviour as it works now does not feel like an issue for them. And, it doesn't seem to be a documentation issue as we've tried our best to say exactly what to do with this file.

So I don't think this is something we'd be looking at another solution for at this time. And, since this isn't something for docs to fix, I'll close this issue here now. We might just have to chalk it up to the fact that it's a special file, and if you try to do something other than its intended, documented purpose, you may not be successful!