Make paraglide files available via Virtual module

[LorisSigrist]

Fixes opral/inlang-paraglide-js#264

This PR adds a useVirtualModule option to paraglide-unplugin (and therefore all it's descendants). This makes a $paraglide virtual module available instead of writing to disk. You can import it like so:

import { languageTag } from "$paraglide/runtime.js"
import * as m from "$paraglide/messages.js"

Types are provided via a .d.ts file with declare module declarations.

Where should the .d.ts file be placed?
In the outdir.

Todos

• Changesets
• Always use virtual module during build, even if a version is written to disk (the virtual module has better code-splitting).
• Pass CI

[changeset-bot]

🦋 Changeset detected

Latest commit: 2a81c4e

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 7 packages

Name	Type
@inlang/paraglide-sveltekit	Minor
@inlang/paraglide-vite	Minor
@inlang/paraglide-unplugin	Minor
@inlang/paraglide-astro	Minor
@inlang/paraglide-webpack	Minor
@inlang/paraglide-sveltekit-example	Patch
@inlang/paraglide-rollup	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[samuelstroschein]

@manuel3108 @benmccann, where should the d.ts files go?

Using the outdir seems reasonable, or hardcoded into /src/paraglide.d.ts and throw when outdir is specified with useVirtualModule (because there no outdir 'really').

[benmccann]

My suggestion would be to make it so that paraglide.d.ts does not have dynamically generated content and then the whole problem goes away. Instead of having availableLanguageTags as a constant defining which languages are available, you could have something such as a method getAvailableLanguageTags(): Set<string>. Then that could be shipped in the paraglide type definitions

[manuel3108]

My suggestion would be to make it so that paraglide.d.ts does not have dynamically generated content and then the whole problem goes away.

This would be the ideal solution.

I'm wondering why this would even be necessary, as the current integration seems to able to just work without such file. At least I was unable to find any .d.ts file inside the outDir. Or is this now necessary because of the virtual modules?

[samuelstroschein]

@benmccann My suggestion would be to make it so that paraglide.d.ts does not have dynamically generated content and then the whole problem goes away.

Not sure if I understand. The d.ts file is dynamically created based on the messages? If the d.ts file is static, there would be no typesafety for messages. Could you clarify how typesafety can be achieved without a dynamic .d.ts file?

At least I was unable to find any .d.ts file inside the outDir. Or is this now necessary because of the virtual modules?

Because Paraglide compiles JS with JSDoc which TypeScript can handle. Virtual modules now take away the JSDoc definitions so TypeScript needs dedicated d.ts files.

In other words, using virtual modules opens up complexity that Paraglide JS did not have before. It just compiled JS files with JSDoc. Works everywhere if the TS setting is set to allowJs: true. But, for some projects allow JS is not possible (opral/inlang-paraglide-js#238) and users have an issue with compiled code in src (opral/inlang-paraglide-js#189, opral/inlang-paraglide-js#264).

[LorisSigrist]

One of the main reasons to use paraglide is the typesafe messages. We can't provide those unless there are dynamically generated type-definitions somewhere. A .d.ts seems like the most sensible place.

I suggest that we place a paraglide.d.ts file in the outdir if useVirtualModule is specified. Seems like the most sensible thing

[benmccann]

Hmm, yeah, I guess there's not much option except to generate the .d.ts file. Though at that point, and I hate to say this with all the work you've put into it already, but I wonder if generating virtual files is even worth it?

Another solution I just thought of would be to instead generate a package in node_modules. That would keep it out of src and let you generate a .d.ts file

[samuelstroschein]

Another solution I just thought of would be to instead generate a package in node_modules. That would keep it out of src and let you generate a .d.ts file

Doesn't work. HMR and everything breaks. We tried that route before. Things become simple once one accepts that Paraglide messages "are source code". Just like generating code from an OpenAPI spec or GraphQL schema. But, I understand that it goes against intuitions (initially).

I suggest that we place a paraglide.d.ts file in the outdir if useVirtualModule is specified. Seems like the most sensible thing

@LorisSigrist Yes, let's emit the d.ts file in the outdir and see how users react. Could you make the config experimental e.g. experimentalUseVirtualModules ?

[benmccann]

HMR and everything breaks.

Looks like you might be able to add a workaround in the Vite plugin to make that work: vitejs/vite#8619 (comment)

[samuelstroschein]

@LorisSigrist is a blocker remaining? Lmk when it's ready to review

[samuelstroschein]

Looks good, but one bug needs to be fixed. Then it can be merged.

The outdir is not considered when creating the paths for the virtual modules. The virtual modules seem to emit by default into $paraglide instead of using the outdir path.

CleanShot.2024-12-09.at.15.49.03.mp4

[LorisSigrist]

Ah, so you want the virtual files to still be importable via the regular file-path, not just a virtual namespace @samuelstroschein?

Should be doable, but we would probably need one .d.ts file per virtual file-path.

[samuelstroschein]

@LorisSigrist I think that using the outdir makes more sense because it doesn't introduce new behavior that needs to be explained i.e. "if you use virtual modules the outdir is ignored, always import with $paraglide".

Should be doable, but we would probably need one .d.ts file per virtual file-path.

Isn't it enough to adjust the d.ts file to use the outdir when declaring the namespaces?

[LorisSigrist]

Path imports can't be done via declare module in a single .d.ts file. The TS compiler won't resolve the path so relative imports and path-aliases like $lib won't work.

SvelteKit generates an entirely separate filetree in the .svelte-kit folder just for types AFAIK. We won't have to do that, we'll just have message.d.ts, runtime.d.ts etc.

[samuelstroschein]

We won't have to do that, we'll just have message.d.ts, runtime.d.ts

Sounds good. And I think it is intuitive.

• Virtual modules = the js files are omitted, only the declaration files emitted.
• skipping per language declaration files seems fine

└── src/
    └── paraglide/
        ├── messages.d.ts
        └── runtime.d.ts

[samuelstroschein]

Expanded the changelog and only emit the runtime.d.ts and messages.d.ts file.

Thank you loris!

/tip 350

[algora-pbc]

🎉🎈 @LorisSigrist has been awarded $350! 🎈🎊

• Share on socials
• Give feedback

[samuelstroschein]

@LorisSigrist how was the process for you with the tipping and PR in general?