chore: deprecates emitPackage

.changeset/neat-buttons-shout.md

@@ -0,0 +1,24 @@
+---
+'@pandacss/types': minor
+---
+
+Deprecates `emitPackage`, it will be removed in the next major version.
+
+## Why?
+
+It's known for causing several issues:
+
+- bundlers sometimes eagerly cache the `node_modules`, leading to `panda codegen` updates to the `styled-system` not
+  visible in the browser
+- auto-imports are not suggested in your IDE.
+- in some IDE the typings are not always reflected properly
+
+## As alternatives, you can use:
+
+- relative paths instead of absolute paths (e.g. `../styled-system/css` instead of `styled-system/css`)
+- use [package.json #imports](https://nodejs.org/api/packages.html#subpath-imports) and/or tsconfig path aliases (prefer
+  package.json#imports when possible, TS 5.4 supports them by default) like `#styled-system/css` instead of
+  `styled-system/css`
+- for a [component library](https://panda-css.com/docs/guides/component-library), use a dedicated workspace package
+  (e.g. `@acme/styled-system`) and use `importMap: "@acme/styled-system"` so that Panda knows which entrypoint to
+  extract, e.g. `import { css } from '@acme/styled-system/css'`

packages/types/src/config.ts

@@ -290,6 +290,17 @@ interface CodegenOptions {
   /**
    * Whether to emit the artifacts to `node_modules` as a package.
    * @default false
+   * @deprecated `emitPackage` is deprecated, it's known for causing several issues:
+   * - bundlers sometimes eagerly cache the `node_modules`, leading to `panda codegen` updates to the `styled-system` not visible in the browser
+   * - auto-imports are not suggested in your IDE.
+   * - in some IDE the typings are not always reflected properly
+   *
+   * As alternatives, you can use:
+   * - relative paths instead of absolute paths (e.g. `../styled-system/css` instead of `styled-system/css`)
+   * - use package.json #imports and/or tsconfig path aliases (prefer package.json#imports when possible, TS 5.4 supports them by default) like `#styled-system/css` instead of `styled-system/css`
+   * @see https://nodejs.org/api/packages.html#subpath-imports
+   * - for a component library, use a dedicated workspace package (e.g. `@acme/styled-system`) and use `importMap: "@acme/styled-system"` so that Panda knows which entrypoint to extract, e.g. `import { css } from '@acme/styled-system/css'`
+   * @see https://panda-css.com/docs/guides/component-library
    */
   emitPackage?: boolean
   /**

website/pages/docs/overview/faq.md

@@ -8,14 +8,6 @@ layout: none
 
 Here's a list of frequently asked questions (FAQ) and how to resolve common issues in Panda.
 
-### Why do I get a "Cannot find X module from 'styled-system'" error?
-
-This error seems to be caused by process timing issues between file writes. This has been fixed recently but if you experience this persistently, consider the following workarounds:
-
-- Check the code to git: Remove the `styled-system` folder from the `.gitignore` file to enable git tracking. Technically, the files emitted will remain the same if the Panda config does not change.
-
-- Use the `emitPackage: true` option and write the files to the `node_modules` directory.
-
 ---
 
 ### How does Panda manage style conflicts ?
@@ -206,12 +198,6 @@ In such a case, check the [`outExtension`](/docs/references/config#outextension)
 
 ---
 
-### How should I use emitPackage with yarn PnP?
-
-When using `emitPackage: true` with yarn PnP, set the `nodeLinker` to 'node-modules' in your `.yarnrc.yml`. This tells Yarn to use the traditional way of linking dependencies, which can solve compatibility issues.
-
----
-
 ### Why does importing `styled` not exist?
 
 You should use [`config.jsxFramework`](/docs/concepts/style-props#configure-jsx) when you need to import styled components. You can then use the [`jsxFactory`](/references/config#jsxfactory) option to set the name of the factory component.

website/pages/docs/references/config.md

@@ -299,29 +299,6 @@ Then the result looks like this:
 
 ## File system options
 
-### emitPackage
-
-**Type**: `boolean`
-
-**Default**: `false`
-
-Whether to emit the artifacts to `node_modules` as a package. Will generate a `package.json` file that contains exports
-for each of the the generated `outdir` entrypoints:
-
-- `styled-system/css`
-- `styled-system/jsx`
-- `styled-system/patterns`
-- `styled-system/recipes`
-- `styled-system/tokens`
-- `styled-system/types`
-- `styled-system/styles.css`
-
-```json
-{
-  "emitPackage": true
-}
-```
-
 ### gitignore
 
 **Type**: `boolean`