diff --git a/.github/workflows/autofix.yml b/.github/workflows/autofix.yml index a37915f1..61c0eefd 100644 --- a/.github/workflows/autofix.yml +++ b/.github/workflows/autofix.yml @@ -24,7 +24,7 @@ jobs: - name: Setup Tools uses: ./.github/setup - name: Fix formatting - run: pnpm run prettier:write + run: pnpm run format - name: Apply fixes uses: autofix-ci/action@635ffb0c9798bd160680f18fd73371e355b85f27 with: diff --git a/.prettierignore b/.prettierignore index 244bfdf5..dadc4de4 100644 --- a/.prettierignore +++ b/.prettierignore @@ -3,6 +3,5 @@ **/.svelte-kit **/coverage **/dist -**/docs **/snap pnpm-lock.yaml diff --git a/docs/ci-cd.md b/docs/ci-cd.md index 5463971d..3f20b8ac 100644 --- a/docs/ci-cd.md +++ b/docs/ci-cd.md @@ -6,13 +6,13 @@ title: CI/CD ## GitHub Workflows - `pr.yml`: - - Runs tests for all pull requests - - Runs `nx affected`, which only executes tasks with invalidated cache - - Also uses `pkg-pr-new` to publish package previews and create links to our examples + - Runs tests for all pull requests + - Runs `nx affected`, which only executes tasks with invalidated cache + - Also uses `pkg-pr-new` to publish package previews and create links to our examples - `release.yml`: - - Runs tests for code merged into release branches - - Runs `nx run-many`, which executes all tasks and ensures the outputs are present (necessary for publishing builds) - - Uses [Changesets](https://github.com/changesets/changesets) to handle versioning and publishing + - Runs tests for code merged into release branches + - Runs `nx run-many`, which executes all tasks and ensures the outputs are present (necessary for publishing builds) + - Uses [Changesets](https://github.com/changesets/changesets) to handle versioning and publishing ## Nx @@ -21,7 +21,7 @@ The TanStack projects use Nx to enable rapid execution of our tests and builds. ### Config Files - `./nx.json`: Main config file, which defines task dependencies, inputs, and outputs -- `./package.json`: Need to manually specify root-level scripts (e.g. `test:format`) +- `./package.json`: Need to manually specify root-level scripts (e.g. `test:eslint`) - `./**/package.json`: Package-level scripts (e.g. `build`) are automatically detected ### Nx Agents diff --git a/docs/dependencies.md b/docs/dependencies.md index 81e69455..62b4e530 100644 --- a/docs/dependencies.md +++ b/docs/dependencies.md @@ -18,4 +18,4 @@ We use 3 separate tools to help manage our dependencies and prevent us from unne ### Renovate - Renovate is a bot which runs on GitHub to scan for outdated or insecure dependencies -- This reduces the burden on maintainers by automatically submitting PRs \ No newline at end of file +- This reduces the burden on maintainers by automatically submitting PRs diff --git a/docs/overview.md b/docs/overview.md index 8cae4667..21fa061e 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -9,10 +9,10 @@ TanStack Config is a collection of tools we currently use between our projects t The following tools are required to use these packages: -- [Node.js v18.17+](https://nodejs.org/en/download/current/) +- [Node.js v20.17.0+](https://nodejs.org/en/download/current/) - [Git CLI](https://git-scm.com/downloads) - [GitHub CLI](https://cli.github.com/) (pre-installed on GitHub Actions) -- [pnpm v8+](https://pnpm.io/) +- [pnpm v10+](https://pnpm.io/) > pnpm is the only supported package manager for TanStack Config. diff --git a/docs/package-structure.md b/docs/package-structure.md index e222d6a5..5f0b3d42 100644 --- a/docs/package-structure.md +++ b/docs/package-structure.md @@ -17,10 +17,6 @@ The following structure ensures packages work optimally with our monorepo/Nx wor - Extends the root-level tsconfig (e.g. `"extends": "../../tsconfig.json"`) - Add any framework-specific options and included files here -### `./vite.config.ts` - -- Includes config for Vitest, and for Vite if [@tanstack/vite-config](./vite.md) is used - ### `./src` - This folder should only include code which gets built and shipped to users @@ -30,3 +26,11 @@ The following structure ensures packages work optimally with our monorepo/Nx wor - This folder should include all test files - It should also include any test setup files required by that framework + +### `./tsdown.config.ts` + +- Defines `tsdown` config, including any framework-specific plugins. + +### `./vitest.config.ts` + +- Defines config for Vitest diff --git a/docs/publish.md b/docs/publish.md index 778847ad..941e6e61 100644 --- a/docs/publish.md +++ b/docs/publish.md @@ -11,7 +11,6 @@ To install the package, run the following command: pnpm add -D @tanstack/publish-config ``` - ## Usage To use the TanStack Config programmatically, you can import the `publish` function: @@ -42,3 +41,24 @@ publish({ > ``` > > in your `package.json` file and use `import` instead of `require`. + +## Trusted Publishing + +Trusted publishing is the new npm strategy to allow publishing packages without npm tokens, using OIDC authentication. It currently requires you to set up for each package individually; however, once enabled, no further interaction is required! + +### Step 1 + +- If the package already has a published version on npm, you can skip this step. +- If the package has never been published, you can publish a "placeholder" package to do the setup process. This CLI tool streamlines this: [setup-npm-trusted-publish](https://github.com/azu/setup-npm-trusted-publish) + +### Step 2 + +- If you're only setting up one package, you can skip this step. Otherwise, the tools below help dramatically when setting up 5+ packages all at once. +- [open-packages-on-npm](https://github.com/antfu/open-packages-on-npm) +- [sxzz's userscript](https://github.com/sxzz/userscripts/blob/main/src/npm-trusted-publisher.md) + +### Step 3 + +- Fill in the fields on the package's settings page, similar to this. You will need to authenticate with MFA to save these settings. + +![Settings](https://raw.githubusercontent.com/TanStack/config/refs/heads/main/media/trusted-publisher.png) diff --git a/docs/vite.md b/docs/vite.md index 921ee38e..942086f0 100644 --- a/docs/vite.md +++ b/docs/vite.md @@ -3,12 +3,16 @@ id: vite title: Vite --- -The Vite build setup is the culmination of several attempts to dual publish ESM and CJS for TanStack projects, while preserving compatibility with all Typescript module resolution options. +The Vite build setup was the result of several attempts to dual publish ESM and CJS for TanStack projects, while preserving compatibility with all Typescript module resolution options. -## Do I Need This? +## Do I need dual publishing? ES Modules (ESM) is the standard for writing JavaScript modules. However, due to the historical dependency on CommonJS (CJS), many ecosystem tools and projects were initially incompatible with ESM. It is becoming exceedingly rare for this to be the case, and I would urge you to consider whether it is necessary to distribute CJS code at all. Sindre Sorhus has a good summary on this issue [here](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c). +## Do I need this package? + +Many alternatives have bene created recently, with the most notable being [tsdown](https://github.com/rolldown/tsdown), built on top of `rolldown`. We will be adopting tsdown for future projects rather than continuing to use our custom Vite setup. + ## Installation To install the package, run the following command: @@ -17,9 +21,20 @@ To install the package, run the following command: pnpm add -D @tanstack/vite-config ``` -## Setup +## Frameworks + +| Framework | Dual Types | ESM only | +| --------- | ----------------------------- | ------------------------------------------------------------------------------------ | +| Vanilla | [tsdown](https://tsdown.dev/) | [tsdown](https://tsdown.dev/) or [tsc](https://www.npmjs.com/package/typescript) | +| Angular | Not required | [ng-packagr](https://www.npmjs.com/package/ng-packagr) (official tool) | +| React | [tsdown](https://tsdown.dev/) | [tsdown](https://tsdown.dev/) or [tsc](https://www.npmjs.com/package/typescript) | +| Solid | Not required | [tsc](https://www.npmjs.com/package/typescript) (preserves JSX, necessary for SSR) | +| Svelte | Not required | [@sveltejs/package](https://www.npmjs.com/package/@sveltejs/package) (official tool) | +| Vue | [tsdown](https://tsdown.dev/) | [tsdown](https://tsdown.dev/) or [tsc](https://www.npmjs.com/package/typescript) | + +## Legacy Setup -The build config is quite opinionated, as it is designed to work with our internal libraries. If you follow the below instructions, it _may_ work for your library too! +The build config is opinionated, and was designed to work with our internal libraries. If you follow the below instructions, it _may_ work for your library too! ### package.json @@ -74,15 +89,3 @@ export default mergeConfig( }), ) ``` - -## Frameworks - -While this config _will_ work with most frameworks with a Vite adapter, it doesn't mean you _should_ use it for all frameworks, as many have their own build tools which are optimised for their ecosystem. When a framework-specific build tool exists, this should be preferred. - -| Framework | Recommendation | -| --------- | -------------------------------------------------------------------------------------------------- | -| Angular | [ng-packagr](https://www.npmjs.com/package/ng-packagr) (official tool) | -| React | [@tanstack/vite-config](https://www.npmjs.com/package/@tanstack/vite-config) (only if you need dual ESM/CJS) | -| Solid | [tsc](https://www.npmjs.com/package/typescript) (preserves JSX, necessary for SSR) | -| Svelte | [@sveltejs/package](https://www.npmjs.com/package/@sveltejs/package) (official tool) | -| Vue | [@tanstack/vite-config](https://www.npmjs.com/package/@tanstack/vite-config) (only if you need dual ESM/CJS) | diff --git a/media/trusted-publisher.png b/media/trusted-publisher.png new file mode 100644 index 00000000..8ce5dfbc Binary files /dev/null and b/media/trusted-publisher.png differ diff --git a/package.json b/package.json index 996bad3f..3a57886c 100644 --- a/package.json +++ b/package.json @@ -15,17 +15,15 @@ "test:build": "nx affected --target=test:build", "test:types": "nx affected --target=test:types", "test:eslint": "nx affected --target=test:eslint", - "test:format": "pnpm run prettier --check", "test:sherif": "sherif", "test:docs": "node scripts/verify-links.ts", "build": "nx affected --target=build", "build:all": "nx run-many --target=build", "watch": "pnpm run build:all && nx watch --all -- pnpm run build:all", "dev": "pnpm run watch", - "prettier": "prettier --experimental-cli --ignore-unknown '**/*'", - "prettier:write": "pnpm run prettier --write", + "format": "prettier --experimental-cli --ignore-unknown '**/*' --write", "changeset": "changeset", - "changeset:version": "changeset version && pnpm install --no-frozen-lockfile && pnpm prettier:write", + "changeset:version": "changeset version && pnpm install --no-frozen-lockfile && pnpm format", "changeset:publish": "changeset publish" }, "nx": {