ant-design/use-with-next.en-US.md at a11d3b4b636abb4dd8c52de4d05ccb25c177bd37

mirror of https://github.com/ant-design/ant-design.git synced 2024-11-24 11:10:01 +08:00

* docs: update nextjs docs

* chore: code clean

* docs: update nextjs docs en

* chore: add Updated tag

* docs: update

2023-12-29 11:55:11 +08:00

6.1 KiB

Raw Blame History

group

order

title

tag

title
Basic Usage

Usage with Next.js

Updated

Next.js is currently the most popular React server-side isomorphic framework in the world. This article will try to use antd components in projects created by Next.js.

Install and Initialization

Before all start, you may need install yarn or pnpm.

The tool will create and initialize environment and dependencies automatically, please try config your proxy setting, or use another npm registry if any network errors happen during it.

After the initialization is complete, we enter the project and start.

$ cd antd-demo
$ npm run dev

Open the browser at http://localhost:3000/. if you see the NEXT logo, it is considered a success.

Import antd

Now we install antd from yarn or npm or pnpm.

Modify src/app/page.tsx, import Button component from antd.

import React from 'react';
import { Button } from 'antd';

const Home = () => (
  <div className="App">
    <Button type="primary">Button</Button>
  </div>
);

export default Home;

OK, you should now see a blue primary button displayed on the page. Next you can choose any components of antd to develop your application. Visit other workflows of Next.js at its User Guide.

You could find that components of antd do not have styles in the first screen. Next, you need to choose different SSR style processing methods according to the mode of Next.js.

Using App Router Updated

If you are using the App Router in Next.js and using antd as your component library, to make the antd component library work better in your Next.js application and provide a better user experience, you can try using the following method to extract and inject antd's first-screen styles into HTML to avoid page flicker.

Install @ant-design/nextjs-registry

Use it in app/layout.tsx

import React from 'react';
import { AntdRegistry } from '@ant-design/nextjs-registry';

const RootLayout = ({ children }: React.PropsWithChildren) => (
  <html lang="en">
    <body>
      <AntdRegistry>{children}</AntdRegistry>
    </body>
  </html>
);

export default RootLayout;

:::warning Next.js App Router currently not support using sub-components via . like <Select.Option /> and <Typography.Text />. Importing them from path would solve this problem. :::

For more detailed information, please refer to with-nextjs-app-router-inline-style。

Using Pages Router

If you are using the Pages Router in Next.js and using antd as your component library, to make the antd component library work better in your Next.js application and provide a better user experience, you can try using the following method to extract and inject antd's first-screen styles into HTML to avoid page flicker.

Install @ant-design/cssinjs

Notes for developers

Please note that when you install @ant-design/cssinjs, you must ensure that the version is consistent with the version of @ant-design/cssinjs in local node_modules of antd, otherwise, multiple React instances will appear, resulting in ctx being unable to be read correctly. (Tips: you can use npm ls @ant-design/cssinjs command to view the local version)

Rewrite pages/_document.tsx

import React from 'react';
import { createCache, extractStyle, StyleProvider } from '@ant-design/cssinjs';
import Document, { Head, Html, Main, NextScript } from 'next/document';
import type { DocumentContext } from 'next/document';

const MyDocument = () => (
  <Html lang="en">
    <Head />
    <body>
      <Main />
      <NextScript />
    </body>
  </Html>
);

MyDocument.getInitialProps = async (ctx: DocumentContext) => {
  const cache = createCache();
  const originalRenderPage = ctx.renderPage;
  ctx.renderPage = () =>
    originalRenderPage({
      enhanceApp: (App) => (props) => (
        <StyleProvider cache={cache}>
          <App {...props} />
        </StyleProvider>
      ),
    });

  const initialProps = await Document.getInitialProps(ctx);
  const style = extractStyle(cache, true);
  return {
    ...initialProps,
    styles: (
      <>
        {initialProps.styles}
        <style dangerouslySetInnerHTML={{ __html: style }} />
      </>
    ),
  };
};

export default MyDocument;

Supports custom themes

// theme/themeConfig.ts
import type { ThemeConfig } from 'antd';

const theme: ThemeConfig = {
  token: {
    fontSize: 16,
    colorPrimary: '#52c41a',
  },
};

export default theme;

Rewrite pages/_app.tsx

import React from 'react';
import { ConfigProvider } from 'antd';
import type { AppProps } from 'next/app';

import theme from './theme/themeConfig';

const App = ({ Component, pageProps }: AppProps) => (
  <ConfigProvider theme={theme}>
    <Component {...pageProps} />
  </ConfigProvider>
);

export default App;

Use antd in page component

import React from 'react';
import { Button } from 'antd';

const Home = () => (
  <div className="App">
    <Button type="primary">Button</Button>
  </div>
);

export default Home;

For more detailed information, please refer to with-nextjs-inline-style.

6.1 KiB Raw Blame History

Install and Initialization

Import antd

Using App Router Updated

Using Pages Router

6.1 KiB

Raw Blame History