[feat] svelte-kit package: Generate type definitions (#1646)

Author: dummdidumm

.changeset/odd-islands-heal.md

@@ -0,0 +1,5 @@
+---
+'@sveltejs/kit': patch
+---
+
+Add types generation to svelte-kit package command

documentation/docs/12-packaging.md

@@ -10,7 +10,8 @@ A SvelteKit component library has the exact same structure as a SvelteKit app, e
 
 Running `svelte-kit package` will take the contents of `src/lib` and generate a `package` directory (which can be [configured](#configuration-package)) containing the following:
 
-- All the files in `src/lib`, unless you [configure](#configuration-package) custom `include`/`exclude` options. Svelte components will be preprocessed (but note the [caveats](#packaging-caveats) below)
+- All the files in `src/lib`, unless you [configure](#configuration-package) custom `include`/`exclude` options. Svelte components will be preprocessed, TypeScript files will be transpiled to JavaScript.
+- Type definitions (`d.ts` files) which are generated for Svelte, JavaScript and TypeScript files. You need to install `typescript >= 4.0.0` and `svelte2tsx >= 0.4.1` for this. Type definitions are placed next to their implementation, hand-written `d.ts` files are copied over as is.
 - A `package.json` that copies the `name`, `version`, `description`, `keywords`, `homepage`, `bugs`, `license`, `author`, `contributors`, `funding`, `repository`, `dependencies`, `private` and `publishConfig` fields from the root of the project, and adds a `"type": "module"` and an `"exports"` field
 
 The `"exports"` field contains the package's entry points. By default, all files in `src/lib` will be treated as an entry point unless they start with (or live in a directory that starts with) an underscore, but you can [configure](#configuration-package) this behaviour. If you have a `src/lib/index.js` or `src/lib/index.svelte` file, it will be treated as the package root.
@@ -37,8 +38,4 @@ The `package` above is referring to the directory name generated, change accordi
 
 ### Caveats
 
-This is a relatively experimental feature and is not yet fully implemented:
-
-- if a preprocessor is specified, `.svelte` files are transformed (meaning they can contain TypeScript, for example), but `.d.ts` files are not generated
-- `.ts` files are not currently transformed, and will cause the process to fail
-- all other files are copied across as-is
+This is a relatively experimental feature and is not yet fully implemented. All files except Svelte files (preprocessed) and TypeScript files (transpiled to JavaScript) are copied across as-is.

documentation/docs/14-configuration.md

@@ -43,6 +43,17 @@ const config = {
 		ssr: true,
 		target: null,
 		trailingSlash: 'never',
+		package: {
+			dir: 'package',
+			exports: {
+				include: ['**'],
+				exclude: ['_*', '**/_*']
+			},
+			files: {
+				include: ['**'],
+				exclude: []
+			}
+		},
 		vite: () => ({})
 	},
 
@@ -149,6 +160,14 @@ Whether to remove, append, or ignore trailing slashes when resolving URLs to rou
 
 > Ignoring trailing slashes is not recommended — the semantics of relative paths differ between the two cases (`./y` from `/x` is `/y`, but from `/x/` is `/x/y`), and `/x` and `/x/` are treated as separate URLs which is harmful to SEO. If you use this option, ensure that you implement logic for conditionally adding or removing trailing slashes from `request.path` inside your [`handle`](#hooks-handle) function.
 
+### package
+
+Options related to [creating a package](#packaging).
+
+- `dir` - output directory
+- `exports` - contains a `includes` and a `excludes` array which specifies which files to mark as exported from the `exports` field of the `package.json`
+- `files` - contains a `includes` and a `excludes` array which specifies which files to process and copy over when packaging
+
 ### vite
 
 A [Vite config object](https://vitejs.dev/config), or a function that returns one. Not all configuration options can be set, since SvelteKit depends on certain values being configured internally.

packages/kit/package.json

@@ -33,7 +33,8 @@
 		"selfsigned": "^1.10.11",
 		"sirv": "^1.0.12",
 		"svelte": "^3.38.2",
-		"svelte-check": "^1.5.2",
+		"svelte2tsx": "~0.4.1",
+		"svelte-check": "^2.2.0",
 		"tiny-glob": "^0.2.8",
 		"typescript": "^4.2.4",
 		"uvu": "^0.5.1"
@@ -53,8 +54,8 @@
 	"scripts": {
 		"build": "rollup -c",
 		"dev": "rollup -cw",
-		"lint": "eslint --ignore-path .gitignore \"src/**/*.{ts,mjs,js,svelte}\" && npm run check-format",
-		"check": "tsc && svelte-check",
+		"lint": "eslint --ignore-path .gitignore --ignore-pattern \"src/core/make_package/test/**\" \"src/**/*.{ts,mjs,js,svelte}\" && npm run check-format",
+		"check": "tsc && svelte-check --ignore \"src/core/make_package/test\"",
 		"format": "prettier --write . --config ../../.prettierrc --ignore-path .gitignore",
 		"check-format": "prettier --check . --config ../../.prettierrc --ignore-path .gitignore",
 		"prepublishOnly": "npm run build",

packages/kit/rollup.config.js

@@ -10,7 +10,8 @@ const external = [].concat(
 	Object.keys(pkg.dependencies || {}),
 	Object.keys(pkg.peerDependencies || {}),
 	Object.keys(process.binding('natives')),
-	'typescript'
+	'typescript',
+	'svelte2tsx'
 );
 
 export default [

packages/kit/src/core/config/options.js

@@ -1,4 +1,4 @@
-const noop = () => {};
+const identity = (/** @type {any} */ id) => id;
 
 /** @typedef {import('./types').ConfigDefinition} ConfigDefinition */
 
@@ -7,7 +7,7 @@ const options = {
 	compilerOptions: {
 		type: 'leaf',
 		default: null,
-		validate: noop
+		validate: identity
 	},
 
 	extensions: {
@@ -169,7 +169,7 @@ const options = {
 	preprocess: {
 		type: 'leaf',
 		default: null,
-		validate: noop
+		validate: identity
 	}
 };
 

packages/kit/src/core/make_package/index.js

@@ -1,8 +1,9 @@
 import * as fs from 'fs';
+import globrex from 'globrex';
+import { createRequire } from 'module';
 import * as path from 'path';
 import { preprocess } from 'svelte/compiler';
-import globrex from 'globrex';
-import { mkdirp, rimraf } from '../filesystem';
+import { mkdirp, rimraf } from '../filesystem/index.js';
 
 /**
  * @param {import('types/config').ValidatedConfig} config
@@ -11,8 +12,14 @@ import { mkdirp, rimraf } from '../filesystem';
 export async function make_package(config, cwd = process.cwd()) {
 	rimraf(path.join(cwd, config.kit.package.dir));
 
+	// Generate type definitions first so hand-written types can overwrite generated ones
+	await emit_dts(config);
+
 	const files_filter = create_filter(config.kit.package.files);
-	const exports_filter = create_filter(config.kit.package.exports);
+	const exports_filter = create_filter({
+		...config.kit.package.exports,
+		exclude: [...config.kit.package.exports.exclude, '*.d.ts']
+	});
 
 	const files = walk(config.kit.files.lib);
 
@@ -57,12 +64,22 @@ export async function make_package(config, cwd = process.cwd()) {
 
 		if (svelte_ext) {
 			// it's a Svelte component
-			// TODO how to emit types?
 			out_file = file.slice(0, -svelte_ext.length) + '.svelte';
 			out_contents = config.preprocess
 				? (await preprocess(source, config.preprocess, { filename })).code
 				: source;
-		} else if (ext === '.ts' && !file.endsWith('.d.ts')) {
+		} else if (ext === '.ts' && file.endsWith('.d.ts')) {
+			// TypeScript's declaration emit won't copy over the d.ts files, so we do it here
+			out_file = file;
+			out_contents = source;
+			if (fs.existsSync(path.join(cwd, config.kit.package.dir, out_file))) {
+				console.warn(
+					'Found already existing file from d.ts generation for ' +
+						out_file +
+						'. This file will be overwritten.'
+				);
+			}
+		} else if (ext === '.ts') {
 			out_file = file.slice(0, -'.ts'.length) + '.js';
 			out_contents = await transpile_ts(filename, source);
 		} else {
@@ -134,7 +151,7 @@ function load_tsconfig(filename, ts) {
 	const { error, config } = ts.readConfigFile(tsconfig_filename, ts.sys.readFile);
 
 	if (error) {
-		throw new Error('Malformed tsconfig');
+		throw new Error('Malformed tsconfig\n' + JSON.stringify(error, null, 2));
 	}
 
 	// Do this so TS will not search for initial files which might take a while
@@ -200,3 +217,30 @@ function write(file, contents) {
 	mkdirp(path.dirname(file));
 	fs.writeFileSync(file, contents);
 }
+
+/**
+ * @param {import('types/config').ValidatedConfig} config
+ */
+export async function emit_dts(config) {
+	const require = createRequire(import.meta.url);
+	const emit = await try_load_svelte2tsx();
+	emit({
+		libRoot: config.kit.files.lib,
+		svelteShimsPath: require.resolve('svelte2tsx/svelte-shims.d.ts'),
+		declarationDir: config.kit.package.dir
+	});
+}
+
+async function try_load_svelte2tsx() {
+	try {
+		const svelte2tsx = (await import('svelte2tsx')).emitDts;
+		if (!svelte2tsx) {
+			throw new Error('Old svelte2tsx version');
+		}
+		return svelte2tsx;
+	} catch (e) {
+		throw new Error(
+			'You need to install svelte2tsx >=0.4.1 if you want to generate type definitions'
+		);
+	}
+}

packages/kit/src/core/make_package/test/fixtures/javascript/expected/Test.svelte

@@ -0,0 +1,12 @@
+<script>
+    import { createEventDispatcher } from 'svelte';
+    /**
+     * @type {string}
+     */
+    export const astring;
+
+    const dispatch = createEventDispatcher();
+    dispatch('event', true);
+</script>
+
+<slot {astring} />

packages/kit/src/core/make_package/test/fixtures/javascript/expected/Test.svelte.d.ts

@@ -0,0 +1,40 @@
+/** @typedef {typeof __propDef.props}  TestProps */
+/** @typedef {typeof __propDef.events}  TestEvents */
+/** @typedef {typeof __propDef.slots}  TestSlots */
+export default class Test extends SvelteComponentTyped<
+	{
+		astring: string;
+	},
+	{
+		event: CustomEvent<any>;
+	} & {
+		[evt: string]: CustomEvent<any>;
+	},
+	{
+		default: {
+			astring: string;
+		};
+	}
+> {
+	get astring(): string;
+}
+export type TestProps = typeof __propDef.props;
+export type TestEvents = typeof __propDef.events;
+export type TestSlots = typeof __propDef.slots;
+import { SvelteComponentTyped } from 'svelte';
+declare const __propDef: {
+	props: {
+		astring: string;
+	};
+	events: {
+		event: CustomEvent<any>;
+	} & {
+		[evt: string]: CustomEvent<any>;
+	};
+	slots: {
+		default: {
+			astring: string;
+		};
+	};
+};
+export {};

packages/kit/src/core/make_package/test/fixtures/javascript/expected/Test2.svelte

@@ -0,0 +1,6 @@
+<script>
+    /**
+     * @type {import('./foo').Foo}
+     */
+    export let foo;
+</script>

packages/kit/src/core/make_package/test/fixtures/javascript/expected/Test2.svelte.d.ts

@@ -0,0 +1,26 @@
+/** @typedef {typeof __propDef.props}  Test2Props */
+/** @typedef {typeof __propDef.events}  Test2Events */
+/** @typedef {typeof __propDef.slots}  Test2Slots */
+export default class Test2 extends SvelteComponentTyped<
+	{
+		foo: boolean;
+	},
+	{
+		[evt: string]: CustomEvent<any>;
+	},
+	{}
+> {}
+export type Test2Props = typeof __propDef.props;
+export type Test2Events = typeof __propDef.events;
+export type Test2Slots = typeof __propDef.slots;
+import { SvelteComponentTyped } from 'svelte';
+declare const __propDef: {
+	props: {
+		foo: import('./foo').Foo;
+	};
+	events: {
+		[evt: string]: CustomEvent<any>;
+	};
+	slots: {};
+};
+export {};

packages/kit/src/core/make_package/test/fixtures/javascript/expected/foo.d.ts

@@ -0,0 +1 @@
+export type Foo = boolean;

packages/kit/src/core/make_package/test/fixtures/javascript/expected/index.d.ts

@@ -0,0 +1 @@
+export { default as Test } from './Test.svelte';

packages/kit/src/core/make_package/test/fixtures/javascript/expected/index.js

@@ -0,0 +1 @@
+export { default as Test } from './Test.svelte';

packages/kit/src/core/make_package/test/fixtures/javascript/expected/package.json

@@ -0,0 +1,13 @@
+{
+	"name": "javascript",
+	"version": "1.0.0",
+	"description": "package-javascript-test",
+	"type": "module",
+	"exports": {
+		"./package.json": "./package.json",
+		"./index.js": "./index.js",
+		"./Test.svelte": "./Test.svelte",
+		"./Test2.svelte": "./Test2.svelte",
+		".": "./index.js"
+	}
+}

packages/kit/src/core/make_package/test/fixtures/javascript/jsconfig.json

@@ -0,0 +1,9 @@
+{
+	"compilerOptions": {
+		"checkJs": true,
+		"paths": {
+			"$lib/*": ["src/lib/*"]
+		}
+	},
+	"include": ["src/**/*.d.ts", "src/**/*.js", "src/**/*.svelte"]
+}

packages/kit/src/core/make_package/test/fixtures/javascript/package.json

@@ -0,0 +1,5 @@
+{
+	"name": "javascript",
+	"version": "1.0.0",
+	"description": "package-javascript-test"
+}

packages/kit/src/core/make_package/test/fixtures/javascript/src/app.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<link rel="icon" href="/favicon.ico" />
+		<meta name="viewport" content="width=device-width, initial-scale=1" />
+		%svelte.head%
+	</head>
+	<body>
+		<div id="svelte">%svelte.body%</div>
+	</body>
+</html>

packages/kit/src/core/make_package/test/fixtures/javascript/src/lib/Test.svelte

@@ -0,0 +1,12 @@
+<script>
+    import { createEventDispatcher } from 'svelte';
+    /**
+     * @type {string}
+     */
+    export const astring;
+
+    const dispatch = createEventDispatcher();
+    dispatch('event', true);
+</script>
+
+<slot {astring} />

packages/kit/src/core/make_package/test/fixtures/javascript/src/lib/Test2.svelte

@@ -0,0 +1,6 @@
+<script>
+    /**
+     * @type {import('./foo').Foo}
+     */
+    export let foo;
+</script>

packages/kit/src/core/make_package/test/fixtures/javascript/src/lib/foo.d.ts

@@ -0,0 +1 @@
+export type Foo = boolean;

packages/kit/src/core/make_package/test/fixtures/javascript/src/lib/index.js

@@ -0,0 +1 @@
+export { default as Test } from './Test.svelte';

packages/kit/src/core/make_package/test/fixtures/javascript/svelte.config.js

@@ -0,0 +1,8 @@
+<script lang="ts">
+    import { createEventDispatcher } from 'svelte';
+    export const astring;
+    const dispatch = createEventDispatcher();
+    dispatch('event', true);
+</script>
+
+<slot {astring} />