feat: generate `@prismicio/client` `Content` namespace

[angeloashmore]

Types of changes

• [ ] Chore (a non-breaking change which is related to package maintenance)
• [ ] Bug fix (a non-breaking change which fixes an issue)
• [x] New feature (a non-breaking change which adds functionality)
• [ ] Breaking change (fix or feature that would cause existing functionality to change)

Description

This PR adds the ability to generate a Content namespace in the @prismicio/client module. The Content namespace allows a developer to easily access generated document and Slice types from a centralized, consistent import path. All document and Slice types are exported from the Content namespace.

Without this PR, developers need to import types manually directly from the generated file. The relative location of the type file changes based on the consuming file, requiring additional thought to resolve. Relative imports also makes code generation outside prismic-ts-codegen (e.g. Slice Machine) more difficult.

The following code shows a simplified version of the generated Content output:

// types.generated.ts

export type PageDocument<Lang extends string = string> =
  prismicT.PrismicDocumentWithUID<Simplify<PageDocumentData>, "page", Lang>;

export type AllDocumentTypes = PageDocument;

export type TextSlice = prismicT.SharedSlice<"text", TextSliceVariation>;

declare module "@prismicio/client" {
  namespace Content {
    export type { PageDocument, AllDocumentTypes, TextSlice };
  }
}

The following example shows how a Slice's React component could be typed using the Content namespace:

// src/slices/Text/index.tsx

import type { Content } from "@prismicio/client";
import type { SliceComponentProps } from "@prismicio/react";

type TextProps = SliceComponentProps<Content.TextSlice>;

export default function Text({ slice }: TextProps) {
  // `slice` is typed as Content.TextSlice
}

All document and Slice types will continue to be exported from the generated file as a top-level export (i.e. they are accessible outside the @prismicio/client module).

Note: Automatic @prismicio/client typing is unaffected by this new Content namespace. The features are similar in that they more easily let a developer make use of the generated content types. Projects are likely to use both integrations.

CLI changes

The CLI will generate the Content namespace by default.

It can be disabled by setting clientIntegration.includeContentNamespace to false in prismicCodegen.config.ts.

// prismicCodegen.config.ts

import type { Config } from "prismic-ts-codegen";

const config: Config = {
  output: "./types.generated.ts",
  models: ["./customtypes/**/index.json", "./slices/**/model.json"],
  clientIntegration: {
    // Disables the Content namespace.
    includeContentNamespace: false,
  },
};

export default config;

generateTypes() changes

The generateTypes() function will not generate the Content namespace by default.

It can be enabled by setting clientIntegration.includeContentNamespace to true.

generateTypes({
  customTypeModels,
  sharedSliceModels,
  clientIntegration: {
    // Enables the Content namespace.
    includeContentNamespace: true,
  },
});

Checklist:

• [x] My change requires an update to the official documentation.
• [x] All TSDoc comments are up-to-date and new ones have been added where necessary.
• [x] All new and existing tests are passing.

🦚

[github-actions[bot]]

size-limit report 📦

Path	Size
dist/index.js	1.07 MB (+0.01% 🔺)
dist/index.cjs	1.08 MB (+0.02% 🔺)

[angeloashmore]

Thanks for the review, @lihbr!

I'll leave the PR open until we test these changes in the pending Slice Machine integration (see this related PR).

[codecov-commenter]

Codecov Report

Merging #28 (89a2806) into main (e61a328) will increase coverage by 0.24%. The diff coverage is 92.30%.

@@            Coverage Diff             @@
##             main      #28      +/-   ##
==========================================
+ Coverage   90.50%   90.75%   +0.24%     
==========================================
  Files          21       21              
  Lines         337      346       +9     
  Branches       82       86       +4     
==========================================
+ Hits          305      314       +9     
  Misses          4        4              
  Partials       28       28              

Impacted Files	Coverage Δ
src/generateTypes.ts	97.43% <92.30%> (+0.76%)	:arrow_up:

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.