Merge pull request #3779 from opral/declaration-files

Add an opt-in `emitTsDeclarations` compiler flag

Author: samuelstroschein

.changeset/locale-declaration-opt-in.md

@@ -0,0 +1,24 @@
+---
+"@inlang/paraglide-js": minor
+---
+
+Add an opt-in `emitTsDeclarations` compiler flag to generate fresh `.d.ts` files (incl. `m` re-export and locale fallbacks) for locale-modules so IDEs stop reporting stale/missing message keys.
+
+Closes https://github.com/opral/inlang-paraglide-js/issues/566
+Closes https://github.com/opral/inlang-paraglide-js/issues/238
+Closes https://github.com/opral/inlang-paraglide-js/issues/160
+
+Example output (locale-modules):
+
+```diff
+  src/paraglide/
+    messages/
+      _index.js
++     _index.d.ts
+      de.js
++     de.d.ts
+      en.js
++     en.d.ts
+    messages.js
++   messages.d.ts
+```

inlang/packages/paraglide/paraglide-js/docs-api/compiler-options.md

@@ -2,15 +2,15 @@
 
 > **CompilerOptions** = `object`
 
-Defined in: [compiler-options.ts:19](https://github.com/opral/monorepo/tree/main/inlang/packages/paraglide/paraglide-js/src/compiler/compiler-options.ts)
+Defined in: [compiler-options.ts:20](https://github.com/opral/monorepo/tree/main/inlang/packages/paraglide/paraglide-js/src/compiler/compiler-options.ts)
 
 ### Properties
 
 #### additionalFiles?
 
 > `optional` **additionalFiles**: `Record`\<`string`, `string`\>
 
-Defined in: [compiler-options.ts:154](https://github.com/opral/monorepo/tree/main/inlang/packages/paraglide/paraglide-js/src/compiler/compiler-options.ts)
+Defined in: [compiler-options.ts:155](https://github.com/opral/monorepo/tree/main/inlang/packages/paraglide/paraglide-js/src/compiler/compiler-options.ts)
 
 The `additionalFiles` option is an array of paths to additional files that should be copied to the output directory.
 
@@ -40,7 +40,7 @@ The output will look like this:
 
 > `optional` **cleanOutdir**: `boolean`
 
-Defined in: [compiler-options.ts:260](https://github.com/opral/monorepo/tree/main/inlang/packages/paraglide/paraglide-js/src/compiler/compiler-options.ts)
+Defined in: [compiler-options.ts:280](https://github.com/opral/monorepo/tree/main/inlang/packages/paraglide/paraglide-js/src/compiler/compiler-options.ts)
 
 Whether to clean the output directory before writing the new files.
 
@@ -54,7 +54,7 @@ true
 
 > `optional` **cookieDomain**: `string`
 
-Defined in: [compiler-options.ts:128](https://github.com/opral/monorepo/tree/main/inlang/packages/paraglide/paraglide-js/src/compiler/compiler-options.ts)
+Defined in: [compiler-options.ts:129](https://github.com/opral/monorepo/tree/main/inlang/packages/paraglide/paraglide-js/src/compiler/compiler-options.ts)
 
 The host to which the cookie will be sent.
 If undefined or empty, the domain attribute is omitted from the cookie, scoping it to the exact current domain only (no subdomains).
@@ -83,7 +83,7 @@ cookieDomain: "example.com" // Cookie: "PARAGLIDE_LOCALE=en; path=/; max-age=345
 
 > `optional` **cookieMaxAge**: `number`
 
-Defined in: [compiler-options.ts:108](https://github.com/opral/monorepo/tree/main/inlang/packages/paraglide/paraglide-js/src/compiler/compiler-options.ts)
+Defined in: [compiler-options.ts:109](https://github.com/opral/monorepo/tree/main/inlang/packages/paraglide/paraglide-js/src/compiler/compiler-options.ts)
 
 The max-age in seconds of the cookie until it expires.
 
@@ -97,7 +97,7 @@ The max-age in seconds of the cookie until it expires.
 
 > `optional` **cookieName**: `string`
 
-Defined in: [compiler-options.ts:102](https://github.com/opral/monorepo/tree/main/inlang/packages/paraglide/paraglide-js/src/compiler/compiler-options.ts)
+Defined in: [compiler-options.ts:103](https://github.com/opral/monorepo/tree/main/inlang/packages/paraglide/paraglide-js/src/compiler/compiler-options.ts)
 
 The name of the cookie to use for the cookie strategy.
 
@@ -111,7 +111,7 @@ The name of the cookie to use for the cookie strategy.
 
 > `optional` **disableAsyncLocalStorage**: `boolean`
 
-Defined in: [compiler-options.ts:189](https://github.com/opral/monorepo/tree/main/inlang/packages/paraglide/paraglide-js/src/compiler/compiler-options.ts)
+Defined in: [compiler-options.ts:209](https://github.com/opral/monorepo/tree/main/inlang/packages/paraglide/paraglide-js/src/compiler/compiler-options.ts)
 
 Replaces AsyncLocalStorage with a synchronous implementation.
 
@@ -126,7 +126,7 @@ leak into another concurrent request.
 
 > `optional` **emitGitIgnore**: `boolean`
 
-Defined in: [compiler-options.ts:203](https://github.com/opral/monorepo/tree/main/inlang/packages/paraglide/paraglide-js/src/compiler/compiler-options.ts)
+Defined in: [compiler-options.ts:223](https://github.com/opral/monorepo/tree/main/inlang/packages/paraglide/paraglide-js/src/compiler/compiler-options.ts)
 
 If `emitGitIgnore` is set to `true` a `.gitignore` file will be emitted in the output directory. Defaults to `true`.
 
@@ -148,7 +148,7 @@ true
 
 > `optional` **emitPrettierIgnore**: `boolean`
 
-Defined in: [compiler-options.ts:168](https://github.com/opral/monorepo/tree/main/inlang/packages/paraglide/paraglide-js/src/compiler/compiler-options.ts)
+Defined in: [compiler-options.ts:169](https://github.com/opral/monorepo/tree/main/inlang/packages/paraglide/paraglide-js/src/compiler/compiler-options.ts)
 
 If `emitPrettierIgnore` is set to `true` a `.prettierignore` file will be emitted in the output directory. Defaults to `true`.
 
@@ -166,11 +166,39 @@ If `emitPrettierIgnore` is set to `true` a `.prettierignore` file will be emitte
 true
 ```
 
+#### emitTsDeclarations?
+
+> `optional` **emitTsDeclarations**: `boolean`
+
+Defined in: [compiler-options.ts:188](https://github.com/opral/monorepo/tree/main/inlang/packages/paraglide/paraglide-js/src/compiler/compiler-options.ts)
+
+Emit `.d.ts` files for the generated output using the TypeScript compiler.
+
+Enable this to give IDEs fresh, explicit typings for generated message modules
+(useful when using `locale-modules` during development). Requires `typescript`
+to be resolvable in your toolchain.
+
+##### Example
+
+```ts
+await compile({
+  project: "./project.inlang",
+  outdir: "./src/paraglide",
+  emitTsDeclarations: true,
+});
+```
+
+##### Default
+
+```ts
+false
+```
+
 #### experimentalMiddlewareLocaleSplitting?
 
 > `optional` **experimentalMiddlewareLocaleSplitting**: `boolean`
 
-Defined in: [compiler-options.ts:77](https://github.com/opral/monorepo/tree/main/inlang/packages/paraglide/paraglide-js/src/compiler/compiler-options.ts)
+Defined in: [compiler-options.ts:78](https://github.com/opral/monorepo/tree/main/inlang/packages/paraglide/paraglide-js/src/compiler/compiler-options.ts)
 
 Whether or not to use experimental middleware locale splitting.
 
@@ -194,7 +222,7 @@ false
 
 > `optional` **fs**: `any`
 
-Defined in: [compiler-options.ts:267](https://github.com/opral/monorepo/tree/main/inlang/packages/paraglide/paraglide-js/src/compiler/compiler-options.ts)
+Defined in: [compiler-options.ts:287](https://github.com/opral/monorepo/tree/main/inlang/packages/paraglide/paraglide-js/src/compiler/compiler-options.ts)
 
 The file system to use. Defaults to `await import('node:fs')`.
 
@@ -204,7 +232,7 @@ Useful for testing the paraglide compiler by mocking the fs.
 
 > `optional` **includeEslintDisableComment**: `boolean`
 
-Defined in: [compiler-options.ts:178](https://github.com/opral/monorepo/tree/main/inlang/packages/paraglide/paraglide-js/src/compiler/compiler-options.ts)
+Defined in: [compiler-options.ts:198](https://github.com/opral/monorepo/tree/main/inlang/packages/paraglide/paraglide-js/src/compiler/compiler-options.ts)
 
 Whether to include an eslint-disable comment at the top of each .js file.
 
@@ -218,7 +246,7 @@ true
 
 > `optional` **isServer**: `string`
 
-Defined in: [compiler-options.ts:96](https://github.com/opral/monorepo/tree/main/inlang/packages/paraglide/paraglide-js/src/compiler/compiler-options.ts)
+Defined in: [compiler-options.ts:97](https://github.com/opral/monorepo/tree/main/inlang/packages/paraglide/paraglide-js/src/compiler/compiler-options.ts)
 
 Tree-shaking flag if the code is running on the server.
 
@@ -242,7 +270,7 @@ typeof window === "undefined"
 
 > `optional` **localStorageKey**: `string`
 
-Defined in: [compiler-options.ts:83](https://github.com/opral/monorepo/tree/main/inlang/packages/paraglide/paraglide-js/src/compiler/compiler-options.ts)
+Defined in: [compiler-options.ts:84](https://github.com/opral/monorepo/tree/main/inlang/packages/paraglide/paraglide-js/src/compiler/compiler-options.ts)
 
 The name of the localStorage key to use for the localStorage strategy.
 
@@ -256,7 +284,7 @@ The name of the localStorage key to use for the localStorage strategy.
 
 > **outdir**: `string`
 
-Defined in: [compiler-options.ts:43](https://github.com/opral/monorepo/tree/main/inlang/packages/paraglide/paraglide-js/src/compiler/compiler-options.ts)
+Defined in: [compiler-options.ts:44](https://github.com/opral/monorepo/tree/main/inlang/packages/paraglide/paraglide-js/src/compiler/compiler-options.ts)
 
 The path to the output directory.
 
@@ -273,7 +301,7 @@ await compile({
 
 > `optional` **outputStructure**: `"locale-modules"` \| `"message-modules"`
 
-Defined in: [compiler-options.ts:254](https://github.com/opral/monorepo/tree/main/inlang/packages/paraglide/paraglide-js/src/compiler/compiler-options.ts)
+Defined in: [compiler-options.ts:274](https://github.com/opral/monorepo/tree/main/inlang/packages/paraglide/paraglide-js/src/compiler/compiler-options.ts)
 
 The `outputStructure` defines how modules are structured in the output.
 
@@ -332,7 +360,7 @@ The benefit are substantially fewer files which is needed in large projects.
 
 > **project**: `string`
 
-Defined in: [compiler-options.ts:31](https://github.com/opral/monorepo/tree/main/inlang/packages/paraglide/paraglide-js/src/compiler/compiler-options.ts)
+Defined in: [compiler-options.ts:32](https://github.com/opral/monorepo/tree/main/inlang/packages/paraglide/paraglide-js/src/compiler/compiler-options.ts)
 
 The path to the inlang project.
 
@@ -349,7 +377,7 @@ await compile({
 
 > `optional` **strategy**: [`Runtime`](runtime/type/README.md#runtime)\[`"strategy"`\]
 
-Defined in: [compiler-options.ts:61](https://github.com/opral/monorepo/tree/main/inlang/packages/paraglide/paraglide-js/src/compiler/compiler-options.ts)
+Defined in: [compiler-options.ts:62](https://github.com/opral/monorepo/tree/main/inlang/packages/paraglide/paraglide-js/src/compiler/compiler-options.ts)
 
 The strategy to use for getting the locale.
 
@@ -375,7 +403,7 @@ Custom strategies with the pattern `custom-[A-Za-z0-9]+` are supported.
 
 > `optional` **urlPatterns**: [`Runtime`](runtime/type/README.md#runtime)\[`"urlPatterns"`\]
 
-Defined in: [compiler-options.ts:172](https://github.com/opral/monorepo/tree/main/inlang/packages/paraglide/paraglide-js/src/compiler/compiler-options.ts)
+Defined in: [compiler-options.ts:192](https://github.com/opral/monorepo/tree/main/inlang/packages/paraglide/paraglide-js/src/compiler/compiler-options.ts)
 
 https://inlang.com/m/gerre34r/library-inlang-paraglideJs/strategy#url
 
@@ -417,6 +445,10 @@ Defined in: [compiler-options.ts:3](https://github.com/opral/monorepo/tree/main/
 
 > `readonly` **emitPrettierIgnore**: `true` = `true`
 
+#### emitTsDeclarations
+
+> `readonly` **emitTsDeclarations**: `false` = `false`
+
 #### experimentalMiddlewareLocaleSplitting
 
 > `readonly` **experimentalMiddlewareLocaleSplitting**: `false` = `false`

inlang/packages/paraglide/paraglide-js/examples/vite/vite.config.js

@@ -9,6 +9,7 @@ export default defineConfig({
 			// forcing locale modules to detect problems during CI/CD
 			// (all other projects use message-modules)
 			outputStructure: "locale-modules",
+			emitTsDeclarations: true,
 		}),
 	],
 	build: {

inlang/packages/paraglide/paraglide-js/src/cli/commands/compile/command.ts

@@ -31,12 +31,18 @@ export const compileCommand = new Command()
 		].join("\n")
 	)
 	.requiredOption("--silent", "Only log errors to the console", false)
+	.option(
+		"--emit-ts-declarations",
+		"Emit .d.ts files for the generated output (requires the typescript package)",
+		defaultCompilerOptions.emitTsDeclarations
+	)
 	.action(
 		async (options: {
 			silent: boolean;
 			project: string;
 			outdir: string;
 			strategy?: CompilerOptions["strategy"];
+			emitTsDeclarations?: CompilerOptions["emitTsDeclarations"];
 		}) => {
 			const logger = new Logger({ silent: options.silent, prefix: true });
 			const path = resolve(process.cwd(), options.project);
@@ -48,6 +54,9 @@ export const compileCommand = new Command()
 					project: path,
 					outdir: options.outdir,
 					strategy: options.strategy ?? defaultCompilerOptions.strategy,
+					emitTsDeclarations:
+						options.emitTsDeclarations ??
+						defaultCompilerOptions.emitTsDeclarations,
 				});
 			} catch (e) {
 				logger.error("Error while compiling inlang project.");

inlang/packages/paraglide/paraglide-js/src/compiler/compile-project.test.ts

@@ -87,6 +87,20 @@ test("emitPrettierIgnore", async () => {
 	expect(_false).not.toHaveProperty(".prettierignore");
 });
 
+test("emitTsDeclarations generates declaration files", async () => {
+	const output = await compileProject({
+		project,
+		compilerOptions: {
+			emitTsDeclarations: true,
+			outputStructure: "locale-modules",
+		},
+	});
+
+	expect(output).toHaveProperty("messages/_index.d.ts");
+	expect(output).toHaveProperty("messages.d.ts");
+	expect(output["messages/_index.d.ts"]).toContain("sad_penguin_bundle");
+});
+
 test("handles message bundles with a : in the id", async () => {
 	const project = await loadProjectInMemory({
 		blob: await newProject({

inlang/packages/paraglide/paraglide-js/src/compiler/compile-project.ts

@@ -10,6 +10,7 @@ import {
 import { createRuntimeFile } from "./runtime/create-runtime.js";
 import { createServerFile } from "./server/create-server-file.js";
 import { createRegistry } from "./registry.js";
+import { emitTsDeclarations } from "./emit-ts-declarations.js";
 
 const outputStructures = {
 	"locale-modules": localeModules,
@@ -99,6 +100,11 @@ export const compileProject = async (args: {
 		}
 	}
 
+	if (optionsWithDefaults.emitTsDeclarations) {
+		const declarations = await emitTsDeclarations(output);
+		Object.assign(output, declarations);
+	}
+
 	return output;
 };
 

inlang/packages/paraglide/paraglide-js/src/compiler/compiler-options.ts

@@ -5,6 +5,7 @@ export const defaultCompilerOptions = {
 	emitGitIgnore: true,
 	includeEslintDisableComment: true,
 	emitPrettierIgnore: true,
+	emitTsDeclarations: false,
 	cleanOutdir: true,
 	disableAsyncLocalStorage: false,
 	experimentalMiddlewareLocaleSplitting: false,
@@ -166,6 +167,25 @@ export type CompilerOptions = {
 	 * @default true
 	 */
 	emitPrettierIgnore?: boolean;
+	/**
+	 * Emit `.d.ts` files for the generated output using the TypeScript compiler.
+	 *
+	 * Enable this to give IDEs fresh, explicit typings for generated message modules
+	 * (useful when using `locale-modules` during development). Requires `typescript`
+	 * to be resolvable in your toolchain.
+	 *
+	 * @example
+	 * ```ts
+	 * await compile({
+	 *   project: "./project.inlang",
+	 *   outdir: "./src/paraglide",
+	 *   emitTsDeclarations: true,
+	 * });
+	 * ```
+	 *
+	 * @default false
+	 */
+	emitTsDeclarations?: boolean;
 	/**
 	 * https://inlang.com/m/gerre34r/library-inlang-paraglideJs/strategy#url
 	 */