@sanity/pkg-utils/dist/index.d.ts

Simple utilities for modern npm packages.

import { PluginItem } from "@babel/core";
import { OptimizeLodashOptions } from "@optimize-lodash/rollup-plugin";
import { PkgExport, PkgExports, PkgExports as PkgExports$1 } from "@sanity/parse-package-json";
import { Options } from "@vanilla-extract/rollup-plugin";
import { PluginOptions } from "babel-plugin-react-compiler";
import { NormalizedOutputOptions, Plugin, Plugin as RollupPlugin, TreeshakingOptions } from "rollup";
type ToggleType = 'error' | 'warn' | 'off';
/**
 * @public
 */
interface StrictOptions {
  /**
   * Disallows a top level `typings` field in `package.json` if it is equal to `exports['.'].source`.
   * @defaultValue 'error'
   */
  noPackageJsonTypings: ToggleType;
  /**
   * Requires specifying `sideEffects` in `package.json`.
   * @defaultValue 'warn'
   */
  noImplicitSideEffects: ToggleType;
  /**
   * Requires specifying `browserslist` in `package.json`, instead of relying on it implicitly being:
   * @example
   * ```
   * "browserslist": "extends @sanity/browserslist-config"
   * ```
   * @defaultValue 'warn'
   */
  noImplicitBrowsersList: ToggleType;
  /**
   * If typescript is used then `types` in `package.json` should be specified for npm listings to show the TS icon.
   * @defaultValue 'error'
   */
  alwaysPackageJsonTypes: ToggleType;
  /**
   * Using `.npmignore` is error prone, it's best practice to always declare `files` instead
   * @defaultValue 'error'
   */
  alwaysPackageJsonFiles: ToggleType;
  /**
   * It's slow to perform type checking while generating dts files, so it's best practice to disable it with a `"noCheck": true` in the tsconfig.json file used by `package.config.ts`
   * @defaultValue 'warn'
   */
  noCheckTypes: ToggleType;
  /**
   * Disallows the `browser` field in `package.json` as the `browser` condition in `exports` is better supported.
   * @defaultValue 'warn'
   */
  noPackageJsonBrowser: ToggleType;
  /**
   * Disallows the `typesVersions` field in `package.json` as TypeScript has long supported conditional exports and the `types` condition.
   * @defaultValue 'warn'
   */
  noPackageJsonTypesVersions: ToggleType;
  /**
   * Warns if `type` field is missing or set to `commonjs`. Future versions will require `"type": "module"`.
   * @defaultValue 'warn'
   */
  preferModuleType: ToggleType;
  /**
   * Warns if `publishConfig.exports` is missing when `source`, `development`, or `monorepo` conditions are used in exports.
   * @defaultValue 'warn'
   */
  noPublishConfigExports: ToggleType;
  /**
   * Disallows `react-is` in `peerDependencies`. It should be in `dependencies` (or `devDependencies`) instead.
   * @defaultValue 'error'
   */
  noReactIsPeerDependency: ToggleType;
  /**
   * Disallows `@sanity/ui` in `peerDependencies`. It should be in `dependencies` (or `devDependencies`) instead.
   * @defaultValue 'error'
   */
  noSanityUiPeerDependency: ToggleType;
  /**
   * Disallows `@sanity/icons` in `peerDependencies`. It should be in `dependencies` (or `devDependencies`) instead.
   * @defaultValue 'error'
   */
  noSanityIconsPeerDependency: ToggleType;
  /**
   * Disallows `sanity` in `dependencies`. It should only be in `devDependencies` and/or `peerDependencies`.
   * @defaultValue 'error'
   */
  noSanityDependency: ToggleType;
  /**
   * Disallows `styled-components` in `dependencies`. It should only be in `devDependencies` and/or `peerDependencies`.
   * @defaultValue 'error'
   */
  noStyledComponentsDependency: ToggleType;
  /**
   * Disallows `react` in `dependencies`. It should only be in `devDependencies` and/or `peerDependencies`.
   * @defaultValue 'error'
   */
  noReactDependency: ToggleType;
  /**
   * Disallows `react-dom` in `dependencies`. It should only be in `devDependencies` and/or `peerDependencies`.
   * @defaultValue 'error'
   */
  noReactDomDependency: ToggleType;
  /**
   * Disallows `@types/react` in `dependencies`. It should only be in `devDependencies` and/or `peerDependencies`, and when declared as a peer dependency the version range should be `*`.
   * @defaultValue 'error'
   */
  noReactTypesDependency: ToggleType;
  /**
   * Disallows `@types/react-dom` in `dependencies`. It should only be in `devDependencies` and/or `peerDependencies`, and when declared as a peer dependency the version range should be `*`.
   * @defaultValue 'error'
   */
  noReactDomTypesDependency: ToggleType;
  /**
   * Disallows `@types/node` in `dependencies`. It should only be in `devDependencies` and/or `peerDependencies`, and when declared as a peer dependency the version range should be `*`.
   * @defaultValue 'error'
   */
  noNodeTypesDependency: ToggleType;
  /**
   * Disallows `rxjs` in `peerDependencies`. It should only be in `dependencies` and/or `devDependencies`.
   * @defaultValue 'error'
   */
  noRxjsPeerDependency: ToggleType;
  /**
   * Disallows `@sanity/client` in `peerDependencies`. It should only be in `dependencies` and/or `devDependencies`.
   * @defaultValue 'error'
   */
  noSanityClientPeerDependency: ToggleType;
}
/** @public */
type PkgFormat = 'commonjs' | 'esm';
/**
 * Options for the `@vanilla-extract/rollup-plugin` integration, including pkg-utils-specific
 * extensions (`minify`, `browserslist`, and `extract.compatMode`).
 * @alpha
 */
interface PkgVanillaExtractOptions extends Omit<Options, 'extract'> {
  /**
   * Minify the extracted CSS with `lightningcss`.
   * @defaultValue true
   */
  minify?: boolean;
  /**
   * Browserslist query passed to `lightningcss` when optimizing the extracted CSS.
   * @defaultValue the project's browserslist config, falling back to pkg-utils' default query
   */
  browserslist?: string | string[];
  /**
   * Different formatting of identifiers (e.g. class names, keyframes, CSS Vars, etc).
   * @defaultValue "short"
   */
  identifiers?: Options['identifiers'];
  /**
   * Extract the CSS into a separate file. pkg-utils always extracts, so this configures _how_.
   */
  extract?: {
    /**
     * Name of the emitted `.css` file (and, with `compatMode`, the `exports` subpath + shim base).
     * @defaultValue "bundle.css"
     */
    name?: string;
    /**
     * Generate a `.css.map` sourcemap file.
     * @defaultValue true
     */
    sourcemap?: boolean;
    /**
     * Compatibility mode automatically wires up the conditional CSS export pattern so userland does
     * not have to. When enabled, pkg-utils:
     *
     * - injects `import "<pkg-name>/<name>"` into each entry chunk (no manual `rollup.output.intro`),
     * - emits a no-op `<name>.js` shim for runtimes that cannot import `.css` files, and
     * - writes the conditional `"./<name>"` export to `package.json`
     *   (`browser`/`style` → the real CSS, `node`/`default` → the shim).
     *
     * The result is that `import "<pkg>/<name>"` resolves to the real CSS in bundlers/browsers and
     * to the no-op shim in Node and similar runtimes. Disable it to wire these up yourself.
     * @defaultValue true
     */
    compatMode?: boolean;
  };
}
/** @public */
type PkgRuntime = '*' | 'browser' | 'node';
/** @public */
type PkgConfigPropertyResolver<T> = (prev: T) => T;
/** @public */
type PkgConfigProperty<T> = PkgConfigPropertyResolver<T> | T;
/** @public */
interface PkgBundle {
  source: string;
  import?: string;
  require?: string;
  runtime?: PkgRuntime;
}
/** @public */
type PkgRuleLevel = 'error' | 'warn' | 'info' | 'off';
/** @public */
interface TSDocCustomTag {
  name: string;
  syntaxKind: 'block' | 'modifier';
  allowMultiple?: boolean;
}
type DtsType = 'api-extractor' | 'rolldown';
/** @public */
interface PkgConfigOptions {
  /** @alpha */
  babel?: {
    plugins?: PluginItem[] | null | undefined;
    /** @alpha */
    reactCompiler?: boolean;
    /** @alpha */
    styledComponents?: boolean | {
      /** @defaultValue true */
      displayName?: boolean;
      /**
       * @defaultValue []
       * @example ["\@xstyled/styled-components", "\@xstyled/styled-components/*"]
       */
      topLevelImportPaths?: string[];
      /** @defaultValue true */
      ssr?: boolean;
      /** @defaultValue false */
      fileName?: boolean;
      /** @defaultValue ["index"] */
      meaninglessFileNames?: string[];
      /** @defaultValue true */
      minify?: boolean;
      /**
       * Transpiles `styled.button`...`` to `styled.button(["..."])` so that the `pure` option can
       * annotate a plain call expression, as pure annotations on tagged template expressions aren't
       * supported by bundlers (https://github.com/rollup/rollup/issues/4035). Without it unused
       * styled components can't be tree-shaken.
       * @defaultValue true
       */
      transpileTemplateLiterals?: boolean;
      namespace?: string;
      /** @defaultValue true */
      pure?: boolean;
    };
  };
  /**
   * Configure the React Compiler.
   * To enable it set `babel.reactCompiler` to `true`
   * @beta */
  reactCompilerOptions?: Partial<PluginOptions>;
  bundles?: PkgBundle[];
  /** @alpha */
  define?: Record<string, string | number | boolean | undefined | null>;
  /**
   * Directory of distributed & bundled files.
   */
  dist?: string;
  exports?: PkgConfigProperty<PkgExports$1>;
  /**
   * Runs `@microsoft/api-extractor` to check that TSDoc tags are valid, and release tags are correct.
   * This is useful for packages that need to be consumed by TSDoc-based tooling.
   * It's enabled by default, it can be disabled by setting `extract: {enabled: false}`
   */
  extract?: {
    /**
     * @defaultValue true
     */
    enabled?: boolean;
    /**
     * When set to false, disables type checking during type definition generation.
     * This is equivalent to setting `"noCheck": true` in tsconfig.json but can be
     * controlled from package.config.ts without needing multiple tsconfig files.
     * @defaultValue undefined (uses tsconfig.json settings)
     */
    checkTypes?: boolean;
    /**
     * Packages in `devDependencies` that are not in `external` are automatically added to the `bundledPackages` config.
     * You can exclude a package from being bundled by using a callback:
     * ```
     * bundledPackages: (prev) => prev.filter(package => package !== 'sanity')
     * ```
     */
    bundledPackages?: PkgConfigProperty<string[]>;
    customTags?: TSDocCustomTag[];
    rules?: {
      'ae-incompatible-release-tags'?: PkgRuleLevel;
      'ae-internal-missing-underscore'?: PkgRuleLevel;
      'ae-missing-release-tag'?: PkgRuleLevel;
      'tsdoc-link-tag-unescaped-text'?: PkgRuleLevel;
      'tsdoc-undefined-tag'?: PkgRuleLevel;
      'tsdoc-unsupported-tag'?: PkgRuleLevel;
    };
  };
  /**
   * Packages to exclude from bundles.
   * Provide an array to merge with default exclusions, use a function to replace them:
   * ```
   * exclude: (prev) => prev.filter(package => package !== 'foo')
   * ```
   */
  external?: PkgConfigProperty<string[]>;
  /**
   * Defaults to `"automatic"`
   */
  jsx?: 'transform' | 'preserve' | 'automatic';
  /**
   * Defaults to `"createElement"`
   */
  jsxFactory?: string;
  /**
   * Defaults to `"Fragment"`
   */
  jsxFragment?: string;
  /**
   * Defaults to `"react"`
   */
  jsxImportSource?: string;
  minify?: boolean;
  /** @alpha */
  rollup?: {
    plugins?: PkgConfigProperty<Plugin[]>;
    output?: Partial<NormalizedOutputOptions>;
    /**
     * Defaults to Rollup's `preset: 'recommended'` tree-shaking options. Anything provided here
     * is merged on top of that preset.
     * @alpha
     */
    treeshake?: TreeshakingOptions;
    /** @alpha */
    experimentalLogSideEffects?: boolean;
    /**
     * Adds [hash] to chunk filenames, generally only useful if `@sanity/pkg-utils` is used to deploy a package directly to a CDN.
     * It's not needed when publishing to npm for consumption by other libraries, bundlers and frameworks.
     * @defaultValue false
     */
    hashChunkFileNames?: boolean;
    /**
     * Optimizes lodash imports using `@optimize-lodash/rollup-plugin` when set to `true`.
     * It's enabled if `lodash` is found in `dependencies` or `peerDependencies`.
     * It will use `lodash-es` for ESM targets if found in `dependencies` or `peerDependencies`.
     * @defaultValue true
     * @alpha
     */
    optimizeLodash?: boolean | OptimizeLodashOptions;
    /**
     * Enables \@vanilla-extract/rollup-plugin to extract CSS into a separate file, with support for
     * minifying the extracted CSS. Pass `true` to use the defaults, or an object to customize.
     *
     * By default (`extract.compatMode: true`) pkg-utils also injects the self-referential
     * `import "<pkg>/bundle.css"`, emits a `bundle.css.js` shim, and writes the conditional
     * `"./bundle.css"` export to `package.json` - see {@link PkgVanillaExtractOptions}.
     * @alpha
     */
    vanillaExtract?: boolean | PkgVanillaExtractOptions;
  };
  /**
   * Default runtime of package exports
   */
  runtime?: PkgRuntime;
  sourcemap?: boolean;
  /**
   * Directory of source files.
   */
  src?: string;
  tsconfig?: string;
  /**
   * Configure what checks are made when running `--strict` builds and checks
   */
  strictOptions?: Partial<StrictOptions>;
  /**
   * .d.ts files can be generated either by using `@microsoft/api-extractor` or `rolldown`.
   * `rolldown` is the faster option, but is not yet stable.
   * @defaultValue 'api-extractor'
   */
  dts?: DtsType;
  /**
   * When using `dts: 'rolldown'`, enables the use of the Go-native TypeScript compiler (`tsgo`) for type generation.
   * By default, `tsgo` is automatically enabled if `@typescript/native-preview` is found in `devDependencies`,
   * or if the installed `typescript` is v7 (which is the Go-native compiler).
   * Set to `true` to explicitly enable or `false` to explicitly disable.
   * Note that `tsgo` cannot be disabled when `typescript` v7 is installed, as v7 no longer ships
   * the JS compiler API that the non-tsgo code path depends on.
   * @alpha
   */
  tsgo?: boolean;
}
/** @public */
declare function defineConfig<const T extends PkgConfigOptions>(configOptions: T): T;
/** @alpha */
declare function loadConfig(options: {
  cwd: string;
  pkgPath: string;
}): Promise<PkgConfigOptions | undefined>;
/** @public */
declare const DEFAULT_BROWSERSLIST_QUERY: string[];
/** @public */
interface PkgTemplateStringOption<T = string> {
  name: string;
  type: 'string';
  description: string;
  initial?: T | ((options: Record<string, any>) => T);
  parse?: (v: string) => T | null;
  validate?: (v: string) => string | true;
}
/** @public */
type PkgTemplateOption<T = string> = PkgTemplateStringOption<T>;
/** @public */
declare function defineTemplateOption<T>(option: PkgTemplateOption<T>): PkgTemplateOption<T>;
export { DEFAULT_BROWSERSLIST_QUERY, type PkgBundle, type PkgConfigOptions, type PkgConfigProperty, type PkgConfigPropertyResolver, type PkgExport, type PkgExports, type PkgFormat, type PkgRuleLevel, type PkgRuntime, type RollupPlugin, type TSDocCustomTag, defineConfig, defineTemplateOption, loadConfig };
//# sourceMappingURL=index.d.ts.map