npm package: @mints-cloud/cxf-codegen
Description: Plasmic CXF codegen library for Next.js applications
Author: Ruben Gomez
Latest version: 1.0.6

# cxf-codegen

Plasmic + CXF integration library for Next.js projects. Provides API call components, server-side rendering helpers, and authentication utilities.

## Installation

```bash
npm install cxf-codegen
```

## Setup

Your project needs thin wrapper files that import from this library. The `create-plasmic-app` CLI generates these automatically, but you can also create them manually:

### `pages/_app.tsx`

```tsx
import '@/styles/globals.css'
import '@mints-cloud/cxf-codegen/register';
import type { AppProps } from 'next/app';
import CxfApp from '@mints-cloud/cxf-codegen/pages/app';
import projectcss from '../components/plasmic/<your-project>/plasmic.module.css';

export default function App(props: AppProps) {
  return <CxfApp {...props} tokenClass={projectcss.plasmic_tokens} />;
}
```

### Configure assets query params from variants

Configure this in `pages/_app.tsx` by passing dynamic asset query params to `CxfApp`.
These params are synced to a cookie and automatically appended by `pages/api/assets/[...path].ts` proxy requests.
Your `pages/api/assets/[...path].ts` file should stay a thin wrapper:

```ts
export { default } from '@mints-cloud/cxf-codegen/pages/api/assets';
```

```tsx
import '@/styles/globals.css'
import '@mints-cloud/cxf-codegen/register';
import type { AppProps } from 'next/app';
import CxfApp from '@mints-cloud/cxf-codegen/pages/app';
import projectcss from '../components/plasmic/<your-project>/plasmic.module.css';
import { useScreenVariants } from '../components/plasmic/<your-project>/PlasmicGlobalVariant__Screen';

export default function App(props: AppProps) {
  const screenVariants = useScreenVariants();
  const variation = screenVariants.includes('mobile')
    ? 'mobile'
    : screenVariants.includes('tablet')
    ? 'tablet'
    : undefined;

  return (
    <CxfApp
      {...props}
      tokenClass={projectcss.plasmic_tokens}
      assetsQueryParams={variation ? { variation } : undefined}
    />
  );
}
```

`assetsQueryParams` accepts any query keys/values, so you can map any Plasmic variant naming to any asset param names you need.

### `pages/api/[...path].ts`

```ts
export { default } from '@mints-cloud/cxf-codegen/pages/api/cxf';
```

### `pages/api/assets/[...path].ts`

```ts
export { default } from '@mints-cloud/cxf-codegen/pages/api/assets';
```

### `pages/plasmic-host.tsx`

```tsx
import '@mints-cloud/cxf-codegen/register';
import {
  PlasmicHost,
  getPlasmicHostServerSideProps,
} from '@mints-cloud/cxf-codegen/pages/plasmic-host';
import projectcss from '../components/plasmic/<your-project>/plasmic.module.css';

export default function MyPlasmicHost() {
  return <PlasmicHost tokenClass={projectcss.plasmic_tokens} />;
}

export const getServerSideProps = getPlasmicHostServerSideProps;
```

The `tokenClass` prop ensures Plasmic design tokens are applied correctly in the canvas.
`getPlasmicHostServerSideProps` returns `notFound: true` when host is disabled.

### `next.config.mjs`

```js
import { cxfNextConfig } from "@mints-cloud/cxf-codegen";
export default cxfNextConfig;
```

## Environment Variables

Set these in your `.env` file:

```
CXF_BASE_URL=https://your-cxf-instance.com
CXF_API_KEY=your-public-api-key
```

Optional:

```
CXF_DEV_API_KEY=your-dev-api-key
CXF_USER_API_KEY=your-user-api-key
NEXT_PUBLIC_ENABLE_PLASMIC_HOST=true
```

`NEXT_PUBLIC_ENABLE_PLASMIC_HOST` controls `/plasmic-host` availability:

- In `production`, host is disabled by default
- In non-production, host is enabled by default
- Set to `true/false` (also supports `1/0`, `yes/no`, `on/off`) to override defaults

## Usage

### ApiCall Component

In Plasmic, use the `ApiCall` component to fetch data:

- **apiType**: `endpoint`, `contact`, `dev`, or `user`
- **path**: API path (e.g., `me`, `blog-posts`)
- **method**: HTTP method
- **params**: Query parameters
- **body**: Request body (for POST/PATCH/PUT/DELETE)

Data is available via `$ctx.response.*`:
- `$ctx.response.data` - The response data
- `$ctx.response.error` - Error message if failed
- `$ctx.response.loading` - Loading state
- `$ctx.response.success` - Boolean for success
- `$ctx.response.failed` - Boolean for failure

### Server-Side Rendering (ISR/SSR)

Use `createServerProps` for pages that need pre-fetched data:

```tsx
import { ServerPageWrapper, createServerProps, ServerPageProps } from "@mints-cloud/cxf-codegen";
import { PlasmicHomepage } from "../components/plasmic/Homepage";

function Homepage(props: ServerPageProps) {
  return (
    <ServerPageWrapper {...props}>
      <GlobalContextsProvider>
        <PageParamsProvider__
          route={useRouter()?.pathname}
          params={useRouter()?.query}
          query={useRouter()?.query}
        >
          <PlasmicHomepage />
        </PageParamsProvider__>
      </GlobalContextsProvider>
    </ServerPageWrapper>
  );
}

export default Homepage;

// ISR (default)
export const { getStaticProps } = createServerProps("/", PlasmicHomepage);

// Or SSR for authenticated pages
export const { getServerSideProps } = createServerProps("/profile", PlasmicProfile, {
  mode: "ssr"
});
```

## Updating

To update the library across all your projects:

```bash
npm update cxf-codegen
```