.server - Server-Only file and folder suffix

[shairez]

What is it about?

Help guarantee that server code will never be bundled with client code

What's the motivation for this proposal?

Problems you are trying to solve:

• Bundler Limitations: Bundlers like Rollup need to know which dependencies or imports should be excluded from the client bundle, but they don't know how to handle Qwik specific cases or if a developer accidently refer to a dep of a dep of a dep that references server only code, the bundler wouldn't tree shake it. This can result in larger client bundles or incorrect inclusion of server-only code.

• Developer Clarity: Mixing client and server code in a single file might reduce the confidence in whether or not server code might "get leaked" by developer bug (referring to it somewhere from the client code, etc) which hurts the DX.

Examples;
QwikDev/qwik#7172

Goals you are trying to achieve:

• Simplify bundler and optimizer processes by making server-only code explicit.

• Improve tree-shaking reliability by ensuring that server-only imports and dependencies are easily identifiable, plus help strengthen security that way.

• Enhance developer experience and improve devs confidence in knowing what won't ever ship to the client by clearly separating client and server code.

Any other context or information you want to share:

This approach aligns with prior art from frameworks like Remix, React and SvelteKit.

Examples in the links below

---

Proposed Solution / Feature

What do you propose?

Adopt a .server filename suffix or a dedicated folder structure to clearly identify server-only files. This would:

Server Suffix: Files with the .server.ts suffix will be treated as server-only. They will be excluded from client-side bundles entirely.

Server Folders (Optional): Alternatively, or in combination, developers could use a /server/ directory to organize server-only files. Files within this folder will follow the same exclusion rules as .server files.

Code examples

Before

// actions.ts
export const fetchData = server$(async () => {
  const data = await fetch('https://api.example.com/data');
  return data.json();
});

export const clientFunction = () => {
  console.log('Client-side logic here');
};

After

// fetchData.server.ts
export const fetchData = async () => {
  const data = await fetch('https://api.example.com/data');
  return data.json();
};

// clientFunction.ts
export const clientFunction = () => {
  console.log('Client-side logic here');
};

---

Links / References

https://github.com/remix-run/remix/blob/main/decisions/0009-do-not-rely-on-treeshaking-for-correctness.md
https://github.com/remix-run/remix/blob/main/decisions/0010-splitting-up-client-and-server-code-in-vite.md
https://svelte.dev/docs/kit/server-only-modules
https://react.dev/reference/rsc/use-server

[shairez]

We've discussed this briefly and agreed this is a good idea to move forward.
When we'll have a champion for it, we'll advance it into an RFC issue.