breaking: update svelte-package

.changeset/clever-pianos-wonder.md

@@ -0,0 +1,5 @@
+---
+'svelte-migrate': minor
+---
+
+feat: add `@sveltejs/package` migration (v1->v2)

.changeset/few-donuts-admire.md

@@ -0,0 +1,5 @@
+---
+'create-svelte': major
+---
+
+breaking: update library scaffolding for `@sveltejs/package` version 2

.changeset/plenty-points-provide.md

@@ -0,0 +1,5 @@
+---
+'@sveltejs/package': major
+---
+
+breaking: remove `package.json` generation and package options from `svelte.config.js`. New default output directory is `dist`. Read the migration guide at https://github.com/sveltejs/kit/pull/8922 to learn how to update

documentation/docs/30-advanced/70-packaging.md

@@ -2,33 +2,105 @@
 title: Packaging
 ---
 
-> `svelte-package` is currently experimental. Non-backward compatible changes may occur in any future release.
-
 You can use SvelteKit to build apps as well as component libraries, using the `@sveltejs/package` package (`npm create svelte` has an option to set this up for you).
 
 When you're creating an app, the contents of `src/routes` is the public-facing stuff; [`src/lib`](modules#$lib) contains your app's internal library.
 
-A component library has the exact same structure as a SvelteKit app, except that `src/lib` is the public-facing bit. `src/routes` might be a documentation or demo site that accompanies the library, or it might just be a sandbox you use during development.
+A component library has the exact same structure as a SvelteKit app, except that `src/lib` is the public-facing bit, and your root `package.json` is used to publish the package. `src/routes` might be a documentation or demo site that accompanies the library, or it might just be a sandbox you use during development.
+
+Running the `svelte-package` command from `@sveltejs/package` will take the contents of `src/lib` and generate a `dist` directory (which can be [configured](#options)) containing the following:
+
+- All the files in `src/lib`. 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` for this. Type definitions are placed next to their implementation, hand-written `d.ts` files are copied over as is. You can [disable generation](#options), but we strongly recommend against it — people using your library might use TypeScript, for which they require these type definition files.
+
+> `@sveltejs/package` version 1 generated a `package.json`. This is no longer the case and it will now use the `package.json` from your project and validate that it is correct instead. If you're still on version 1, see [this PR](https://github.com/sveltejs/kit/pull/8922) for migration instructions.
+
+## Anatomy of a package.json
+
+Since you're now building a library for public use, the contents of your `package.json` will become more important. Through it, you configure the entry points of your package, which files are published to npm, and which dependencies your library has. Let's go through the most important fields one by one.
+
+### name
+
+This is the name of your package. It will be available for others to install using that name, and visible on `https://npmjs.com/package/<name>`.
+
+```json
+{
+	"name": "your-library"
+}
+```
+
+Read more about it [here](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#name).
+
+### license
+
+Every package should have a license field so people know how they are allowed to use it. A very popular license which is also very permissive in terms of distribution and reuse without warranty is `MIT`.
+
+```json
+{
+	"license": "MIT"
+}
+```
+
+Read more about it [here](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#license). Note that you should also include a `LICENSE` file in your package.
+
+### files
+
+This tells npm which files it will pack up and upload to npm. It should contain your output folder (`dist` by default). Your `package.json` and `README` and `LICENSE` will always be included, so you don't need to specify them.
+
+```json
+{
+	"files": ["dist"]
+}
+```
+
+To exclude unnecessary files (such as unit tests, or modules that are only imported from `src/routes` etc) you can add them to an `.npmignore` file. This will result in smaller packages that are faster to install.
 
-Running the `svelte-package` command from `@sveltejs/package` will take the contents of `src/lib` and generate a `package` directory (which can be [configured](configuration)) containing the following:
+Read more about it [here](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#files).
 
-- All the files in `src/lib`, unless you [configure](configuration) 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` for this. Type definitions are placed next to their implementation, hand-written `d.ts` files are copied over as is. You can [disable generation](configuration), but we strongly recommend against it — people using your library might use TypeScript, for which they require these type definition files.
-- A `package.json` copied from the project root with all fields except `"scripts"`, `"publishConfig.directory"` and `"publishConfig.linkDirectory"`. The `"dependencies"` field is included, which means you should add packages that you only need for your documentation or demo site to `"devDependencies"`. A `"type": "module"` and an `"exports"` field will be added if it's not defined in the original file.
+### exports
 
-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) this behaviour. If you have a `src/lib/index.js` or `src/lib/index.svelte` file, it will be treated as the package root.
+The `"exports"` field contains the package's entry points. If you set up a new library project through `npm create svelte@latest`, it's set to a single export, the package root:
 
-For example, if you had a `src/lib/Foo.svelte` component and a `src/lib/index.js` module that re-exported it, a consumer of your library could do either of the following:
+```json
+{
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"svelte": "./dist/index.js"
+		}
+	}
+}
+```
+
+This tells bundlers and tooling that your package only has one entry point, the root, and everything should be imported through that, like this:
 
 ```js
-// @filename: ambient.d.ts
-declare module 'your-library';
+// @errors: 2307
+import { Something } from 'your-library';
+```
 
-// @filename: index.js
-// ---cut---
-import { Foo } from 'your-library';
+The `types` and `svelte` keys are [export conditions](https://nodejs.org/api/packages.html#conditional-exports). They tell tooling what file to import when they look up the `your-library` import:
+
+- TypeScript sees the `types` condition and looks up the type definition file. If you don't publish type definitions, omit this condition.
+- Svelte-aware tooling sees the `svelte` condition and knows this is a Svelte component library. If you publish a library that does not export any Svelte components and that could also work in non-Svelte projects (for example a Svelte store library), you can replace this condition with `default`.
+
+> Previous versions of `@sveltejs/package` also added a `package.json` export. This is no longer part of the template because all tooling can now deal with a `package.json` not being explicitly exported.
+
+You can adjust `exports` to your liking and provide more entry points. For example, if instead of a `src/lib/index.js` file that re-exported components you wanted to expose a `src/lib/Foo.svelte` component directly, you could create the following export map...
+
+```json
+{
+	"exports": {
+		"./Foo.svelte": {
+			"types": "./dist/Foo.svelte.d.ts",
+			"svelte": "./dist/Foo.svelte"
+		}
+	}
+}
 ```
 
+...and a consumer of your library could import the component like so:
+
 ```js
 // @filename: ambient.d.ts
 declare module 'your-library/Foo.svelte';
@@ -38,26 +110,78 @@ declare module 'your-library/Foo.svelte';
 import Foo from 'your-library/Foo.svelte';
 ```
 
-> You should avoid using [SvelteKit-specific modules](modules) like `$app` in your packages unless you intend for them to only be consumable by other SvelteKit projects. E.g. rather than using `import { browser } from '$app/environment'` you could use [`import.meta.env.SSR`](https://vitejs.dev/guide/env-and-mode.html#env-variables) to make the library available to all Vite-based projects or better yet use [Node conditional exports](https://nodejs.org/api/packages.html#conditional-exports) to make it work for all bundlers. You may also wish to pass in things like the current URL or a navigation action as a prop rather than relying directly on `$app/stores`, `$app/navigation`, etc. Writing your app in this more generic fashion will also make it easier to setup tools for testing, UI demos and so on.
+In general, each key of the exports map is the path the user will have to use to import something from your package, and the value is the path to the file that will be imported or a map of export conditions which in turn contains these file paths.
+
+Read more about `exports` [here](https://nodejs.org/docs/latest-v18.x/api/packages.html#package-entry-points).
+
+### svelte
+
+This is a legacy field that enabled tooling to recognise Svelte component libraries. It's no longer necessary when using the `svelte` [export condition](#anatomy-of-a-package-json-exports), but for backwards compatibility with outdated tooling that doesn't yet know about export conditions it's good to keep it around. It should point towards your root entry point.
+
+```json
+{
+	"svelte": "./dist/index.js"
+}
+```
+
+## Best practices
+
+You should avoid using [SvelteKit-specific modules](modules) like `$app` in your packages unless you intend for them to only be consumable by other SvelteKit projects. E.g. rather than using `import { browser } from '$app/environment'` you could use `import { BROWSER } from 'esm-env'` ([see esm-env docs](https://github.com/benmccann/esm-env)). You may also wish to pass in things like the current URL or a navigation action as a prop rather than relying directly on `$app/stores`, `$app/navigation`, etc. Writing your app in this more generic fashion will also make it easier to setup tools for testing, UI demos and so on.
+
+Ensure that you add [aliases](/docs/configuration#alias) via `svelte.config.js` (not `vite.config.js` or `tsconfig.json`), so that they are processed by `svelte-package`.
+
+You should think carefully about whether or not the changes you make to your package are a bug fix, a new feature, or a breaking change, and update the package version accordingly. Note that if you remove any paths from `exports` or any `export` conditions inside them from your existing library, that should be regarded as a breaking change.
+
+```diff
+{
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+// changing `svelte` to `default` is a breaking change:
+-			"svelte": "./dist/index.js"
++			"default": "./dist/index.js"
+		},
+// removing this is a breaking change:
+-		"./foo": {
+-			"types": "./dist/foo.d.ts",
+-			"svelte": "./dist/foo.js",
+-			"default": "./dist/foo.js"
+-		},
+// adding this is ok:
++		"./bar": {
++			"types": "./dist/bar.d.ts",
++			"svelte": "./dist/bar.js",
++			"default": "./dist/bar.js"
++		}
+	}
+}
+```
 
 ## Options
 
 `svelte-package` accepts the following options:
 
 - `-w`/`--watch` — watch files in `src/lib` for changes and rebuild the package
+- `-i`/`--input` — the input directory which contains all the files of the package. Defaults to `src/lib`
+- `-o`/`--o` — the output directory where the processed files are written to. You `package.json`'s `exports` should point to files inside there, and the `files` array should include that folder. Defaults to `dist`
+- `-t`/`--types` — whether or not to create type definitions (`d.ts` files). We strongly recommend doing this as it fosters ecosystem library quality. Defaults to `true`
 
 ## Publishing
 
 To publish the generated package:
 
 ```sh
-npm publish ./package
+npm publish
 ```
 
-The `./package` above is referring to the directory name generated, change accordingly if you configure a custom [`package.dir`](configuration).
-
 ## Caveats
 
-All relative file imports need to be fully specified, adhering to Node's ESM algorithm. This means you cannot import the file `src/lib/something/index.js` like `import { something } from './something`, instead you need to import it like this: `import { something } from './something/index.js`. If you are using TypeScript, you need to import `.ts` files the same way, but using a `.js` file ending, _not_ a `.ts` file ending (this isn't under our control, the TypeScript team has made that decision). Setting `"moduleResolution": "NodeNext"` in your `tsconfig.json` or `jsconfig.json` will help you with this.
+All relative file imports need to be fully specified, adhering to Node's ESM algorithm. This means that for a file like `src/lib/something/index.js`, you must include the filename with the extension:
+
+```diff
+-import { something } from './something';
++import { something } from './something/index.js';
+
+If you are using TypeScript, you need to import `.ts` files the same way, but using a `.js` file ending, _not_ a `.ts` file ending. (This is a TypeScript design decision outside our control.) Setting `"moduleResolution": "NodeNext"` in your `tsconfig.json` or `jsconfig.json` will help you with this.
 
-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.
+All files except Svelte files (preprocessed) and TypeScript files (transpiled to JavaScript) are copied across as-is.

packages/create-svelte/templates/skeletonlib/.meta.json

@@ -1,4 +1,4 @@
 {
-	"title": "Library skeleton project",
+	"title": "Library project",
 	"description": "Barebones scaffolding for your new Svelte library"
 }

packages/create-svelte/templates/skeletonlib/package.template.json

@@ -3,17 +3,31 @@
 	"version": "0.0.1",
 	"scripts": {
 		"dev": "vite dev",
-		"build": "svelte-kit sync && svelte-package",
-		"prepublishOnly": "echo 'Did you mean to publish `./package/`, instead of `./`?' && exit 1"
+		"build": "vite build && npm run package",
+		"preview": "vite preview",
+		"package": "svelte-kit sync && svelte-package && publint",
+		"prepublishOnly": "npm run package && publint"
+	},
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"svelte": "./dist/index.js"
+		}
+	},
+	"peerDependencies": {
+		"svelte": "^3.54.0"
 	},
 	"devDependencies": {
 		"@sveltejs/adapter-auto": "^2.0.0",
 		"@sveltejs/kit": "^1.5.0",
 		"@sveltejs/package": "^1.0.0",
+		"publint": "^0.1.9",
 		"svelte": "^3.54.0",
 		"tslib": "^2.4.1",
 		"typescript": "^4.9.3",
 		"vite": "^4.0.0"
 	},
+	"svelte": "./dist/index.js",
+	"types": "./dist/index.d.ts",
 	"type": "module"
 }

packages/migrate/migrations/package/index.js

@@ -0,0 +1,80 @@
+import fs from 'fs';
+import colors from 'kleur';
+import path from 'path';
+import prompts from 'prompts';
+import { pathToFileURL } from 'url';
+import { bail, check_git } from '../../utils.js';
+import { migrate_config } from './migrate_config.js';
+import { migrate_pkg } from './migrate_pkg.js';
+
+export async function migrate() {
+	if (!fs.existsSync('svelte.config.js')) {
+		bail('Please re-run this script in a directory with a svelte.config.js');
+	}
+	if (!fs.existsSync('package.json')) {
+		bail('Please re-run this script in a directory with a package.json');
+	}
+
+	console.log(
+		colors
+			.bold()
+			.yellow(
+				'\nThis will update your svelte.config.js and package.json in the current directory\n'
+			)
+	);
+
+	const use_git = check_git();
+
+	const response = await prompts({
+		type: 'confirm',
+		name: 'value',
+		message: 'Continue?',
+		initial: false
+	});
+
+	if (!response.value) {
+		process.exit(1);
+	}
+
+	const { default: config } = await import(pathToFileURL(path.resolve('svelte.config.js')).href);
+	const has_package_config = !!config.package;
+
+	config.package = {
+		source: path.resolve(config.kit?.files?.lib ?? config.package?.source ?? 'src/lib'),
+		dir: config.package?.dir ?? 'package',
+		exports:
+			config.package?.exports ??
+			((/** @type {string} */ filepath) => !/^_|\/_|\.d\.ts$/.test(filepath)),
+		files: config.package?.files ?? (() => true),
+		emitTypes: config.package?.emitTypes ?? true
+	};
+	config.extensions = config.extensions ?? ['.svelte'];
+
+	migrate_pkg(config);
+
+	if (has_package_config) {
+		migrate_config();
+	}
+
+	console.log(colors.bold().green('✔ Your project has been migrated'));
+
+	console.log('\nRecommended next steps:\n');
+
+	const cyan = colors.bold().cyan;
+
+	const tasks = [
+		use_git && cyan('git commit -m "migration to @sveltejs/package v2"'),
+		`Review the migration guide at https://github.com/sveltejs/kit/pull/8922`,
+		`Read the updated docs at https://kit.svelte.dev/docs/packaging`
+	].filter(Boolean);
+
+	tasks.forEach((task, i) => {
+		console.log(`  ${i + 1}: ${task}`);
+	});
+
+	console.log('');
+
+	if (use_git) {
+		console.log(`Run ${cyan('git diff')} to review changes.\n`);
+	}
+}