Next.js
refine can be used with Next.js to SSR your pages. It doesn't get in the way and follows Next.js conventions and also provides helper modules when necessary.
Setup
nextjs-router package provided by refine must be used for the routerProvider
- npm
- pnpm
- yarn
npm i @refinedev/nextjs-router
pnpm add @refinedev/nextjs-router
yarn add @refinedev/nextjs-router
We recommend using create refine-app
to initialize your refine projects. It configures the project according to your needs including SSR with Next.js.
- npm
- pnpm
- yarn
npm create refine-app@latest -- -o refine-nextjs my-refine-nextjs-app
pnpm create refine-app@latest -- -o refine-nextjs my-refine-nextjs-app
yarn create refine-app@latest -- -o refine-nextjs my-refine-nextjs-app
Only supports yarn@1 version.
To make this example more visual, we used the @pankod/refine-antd
package. If you are using Refine headless, you need to provide the components, hooks or helpers imported from the @pankod/refine-antd
package.
Usage
<Refine>
must wrap your pages in a custom App component. This way your pages are integrated to refine.
import { AppProps } from "next/app";
import { Refine } from "@pankod/refine-core";
import {
Layout,
ReadyPage,
useNotificationProvider,
ErrorComponent,
} from "@pankod/refine-antd";
import dataProvider from "@pankod/refine-simple-rest";
import routerProvider from "@pankod/refine-nextjs-router";
import { PostList, PostEdit, PostCreate, PostShow } from "pages/posts";
import { UserList, UserShow } from "pages/users";
const API_URL = "https://api.fake-rest.refine.dev";
function MyApp({ Component, pageProps }: AppProps): JSX.Element {
return (
<Refine
routerProvider={routerProvider}
dataProvider={dataProvider(API_URL)}
Layout={Layout}
ReadyPage={ReadyPage}
notificationProvider={useNotificationProvider}
catchAll={<ErrorComponent />}
resources={[
{
name: "posts",
list: PostList,
create: PostCreate,
edit: PostEdit,
show: PostShow,
},
{
name: "users",
list: UserList,
show: UserShow,
},
]}
>
<Component {...pageProps} />
</Refine>
);
}
export default MyApp;
Custom Page
Let's say we want to show a list of users in /users
. After creating users.tsx
under pages
in your Nextjs app, we can use the useTable
hook to list the users in a table:
import { LayoutWrapper } from "@pankod/refine-core";
import { useTable, List, Table } from "@pankod/refine-antd";
const API_URL = "https://api.fake-rest.refine.dev";
export const UserList: React.FC = () => {
const { tableProps } = useTable<IUser>({
resource: "users",
});
return (
<LayoutWrapper>
<List title="Users">
<Table {...tableProps} rowKey="id">
<Table.Column dataIndex="id" title="ID" sorter />
<Table.Column dataIndex="firstName" title="Name" />
</Table>
</List>
</LayoutWrapper>
);
};
interface IUser {
id: number;
firstName: string;
}
export default UserList;
If you want to handle your resource
with a custom page or create a custom page with or without a resource, these will not be visible in the <Sider />
component. You can trick the <Sider/>
by passing an empty resource to show your custom route in it.
const App = () => (
<Refine
resources={[
// This will add an item to `<Sider/>` with route `/my-custom-item`
{ name: "my-custom-item", list: () => null },
]}
/>
);
Notice how we passed resource
prop to useTable
. This is necessary since for useTable
to be able to get resource
name from route, it needs to be a route parameter in a dynamic route. Refer here where standard CRUD pages can be built with dynamic routing.
We also used <LayoutWrapper>
to show the page in the layout provided to <Refine>
. This is deliberately opt-in to provide flexibility. If you're building a standard CRUD page layout can be baked in automatically.
SSR
refine uses react-query in its hooks for data management. Following react-query's guide, SSR can be achieved like this:
import { GetServerSideProps } from "next";
import dataProvider from "@pankod/refine-simple-rest";
import {
LayoutWrapper,
GetListResponse,
} from "@pankod/refine-core";
import { useTable, List, Table } from "@pankod/refine-antd";
const API_URL = "https://api.fake-rest.refine.dev";
export const UserList: React.FC<{ users: GetListResponse<IUser> }> = ({
users,
}) => {
const { tableProps } = useTable<IUser>({
resource: "users",
queryOptions: {
initialData: users,
},
});
return (
<LayoutWrapper>
<List title="Users">
<Table {...tableProps} rowKey="id">
<Table.Column dataIndex="id" title="ID" sorter />
<Table.Column dataIndex="firstName" title="Name" />
</Table>
</List>
</LayoutWrapper>
);
};
export const getServerSideProps: GetServerSideProps = async (context) => {
const data = await dataProvider(API_URL).getList({
resource: "users",
});
return {
props: { users: data },
};
};
interface IUser {
id: number;
firstName: string;
}
export default UserList;
We use the getList
method from our dataProvider
to fetch users
data and pass through props
as conventionally done in Next.js. Then users
data is available in the props of our /users
page. useTable
can take options for underlying react-query queries with queryOptions
. Passing users
data to its initialData
loads the data on server side.
We used getList
from dataProvider
but data can be fetched in any way you desire.
Standard CRUD Page
nextjs-router package provides NextRouteComponent
for routing in refine resources. Simply export the component from the page and add a data fetching function. While you can create pages with defined params like [resource]/[action]/[id].tsx
, we recommend using a catch-all route to handle all refine routing in a single file. You can start by creating a [[...refine]].tsx
file under pages
in your Nextjs app:
export { NextRouteComponent as default } from "@pankod/refine-nextjs-router";
You can also define routes without using [[...refine]].tsx
file like below, but a catch-all route is an easier approach with nested route support.
Export NextRouteComponent
as default in the following pages:
pages/[resource].tsx
pages/[resource]/[action].tsx
pages/[resource]/[action]/[id].tsx
pages/index.tsx
NextRouteComponent
will use route parameters resource
and action
and render the associated component defined in resources
.
list
component will be rendered for/[resource]
routecreate
,edit
andshow
will be rendered for/[resource]/[action]
and/[resource]/[action]/[id]
routes- For the root
/
route, it will renderDashboardPage
if it's defined and if not will navigate to the first resource inresources
.
NextRouteComponent
will wrap the page with Layout
provided to <Refine>
SSR
NextRouteComponent
accepts a initialData
prop for SSR data.
type NextRouteComponentProps = {
initialData?: any;
};
initialData
must be passed as props from getServerSideProps
. NextRouteComponent
will pass this data as initialData
to the list
, create
, edit
, and show
components.
For example, for a list
component that will be rendered for /[resource]
, the page can use SSR like this:
export { NextRouteComponent as default } from "@pankod/refine-nextjs-router";
import { handleRefineParams } from "@pankod/refine-nextjs-router";
import dataProvider from "@pankod/refine-simple-rest";
import { GetServerSideProps } from "next";
const API_URL = "https://api.fake-rest.refine.dev";
export const getServerSideProps: GetServerSideProps = async (context) => {
const { resource, action, id } = handleRefineParams(context.params?.refine);
try {
if (resource && action === "show" && id) {
const data = await dataProvider(API_URL).getOne({
// we're slicing the resource param to get the resource name from the last part
resource: resource.slice(resource.lastIndexOf("/") + 1),
id,
});
return {
props: {
initialData: data,
},
};
} else if (resource && !action && !id) {
const data = await dataProvider(API_URL).getList({
// we're slicing the resource param to get the resource name from the last part
resource: resource.slice(resource.lastIndexOf("/") + 1),
});
return {
props: {
initialData: data,
},
};
}
} catch (error) {
return { props: {} };
}
return { props: {} };
};
And in the list
component for a resource
e.g. "posts":
import { GetListResponse, IResourceComponentsProps } from "@pankod/refine-core";
import { useTable, List, Table } from "@pankod/refine-antd";
export const PostList: React.FC<
IResourceComponentsProps<GetListResponse<IPost>>
> = ({ initialData }) => {
const { tableProps } = useTable<IPost>({
queryOptions: {
initialData,
},
});
return (
<List>
<Table {...tableProps} rowKey="id">
<Table.Column dataIndex="id" title="ID" />
<Table.Column dataIndex="status" title="Status" />
</Table>
</List>
);
};
interface IPost {
id: number;
firstName: string;
}
You can also achieve SSR with getStaticProps
and getStaticPaths
for static generation. All you need to do is to add the paths you want to statically generate to getStaticPaths
and pass the data as initialData
from getStaticProps
.
Server Side Authentication
nextjs-router package provides checkAuthentication
to easily handle server side authentication.
export { NextRouteComponent as default } from "@pankod/refine-nextjs-router";
import { checkAuthentication } from "@pankod/refine-nextjs-router";
import { GetServerSideProps } from "next";
import { authProvider } from "../../src/authProvider";
const API_URL = "https://api.fake-rest.refine.dev";
export const getServerSideProps: GetServerSideProps = async (context) => {
const { isAuthenticated, ...props } = await checkAuthentication(
authProvider,
context,
);
if (!isAuthenticated) {
return props;
}
return {
props: {},
};
};
checkAuthentication
expects your authProvider
and getServerSideProps's context
. It uses the checkAuth
from the authProvider
to check for authentication and returns isAuthenticated
accordingly. It also returns a redirect
object to handle unauthenticated case. It redirects to /login
while keeping the original route to be navigated to after successful login.
syncWithLocation
and Query Parameters in SSR
If syncWithLocation
is enabled, query parameters must be handled while doing SSR.
import { GetServerSideProps } from "next";
import { parseTableParamsFromQuery } from "@pankod/refine-core";
import dataProvider from "@pankod/refine-simple-rest";
const API_URL = "https://api.fake-rest.refine.dev";
export const getServerSideProps: GetServerSideProps = async (context) => {
const { parsedCurrent, parsedPageSize, parsedSorter, parsedFilters } =
parseTableParamsFromQuery(context.query);
const data = await dataProvider(API_URL).getList({
resource: "users",
filters: parsedFilters,
pagination: {
current: parsedCurrent || 1,
pageSize: parsedPageSize || 10,
},
sort: parsedSorter,
});
return {
props: { users: data },
};
};
parseTableParams
parses the query string and returns query parameters(refer here for their interfaces). They can be directly used for dataProvider
methods that accepts them.
appDir
Support
Next.js introduced a new way of defining pages within the app/
directory. This new directory has support for layouts, nested routes, and uses Server Components by default. To learn more about the feature check out Next.js Beta docs
refine also follows this feature and provides a way to use appDir
with your refine apps.
app/
is currently in beta and is not recommended for production use in Next.js. In refine, we're providing the app/
support as experimental and not recommended for production use.
To start using app/
with refine, you need to set create the refine routes in your /app
directory with the following convention:
your-project
└── app
└── [[...refine]]
├── layout.tsx
└── page.tsx
Initializing <Refine/>
in layout.tsx
"use client";
import routerProvider from "@pankod/refine-nextjs-router/app";
export default function RefineLayout({
children,
params,
}: {
children: React.ReactNode;
params: Record<"refine", string[]>;
}) {
return (
<Refine
routerProvider={routerProvider.call({ params })}
/* ... */
>
{children}
</Refine>
);
}
We need to bind the params
to the routerProvider
and call it to initialize the routerProvider
. This is because the params
are not available via hooks for refine to use.
Creating page.tsx
"use client";
import { NextRouteComponent } from "@pankod/refine-nextjs-router/app";
export default NextRouteComponent;
Note that we're importing NextRouteComponent
from @pankod/refine-nextjs-router/app
instead of @pankod/refine-nextjs-router
. This is because we're using the app/
directory and we need to import the app
version of the NextRouteComponent
.
"use client";
is a directive that instructs Next.js to opt-out from Server Components. This is because refine and dependencies are not yet compatible with Server Components. That's why we're using it in both layout.tsx
and page.tsx
files.
checkAuthentication
does not work with app/
directory. You need to handle the authentication of your views while using app/
directory.
refine aims to provide a middleware for app/
directory to substitute checkAuthentication
but it's not available yet.
You can find the app/
directory example with refine in examples/nextjs/appdir
Example
npm create refine-app@latest -- --example with-nextjs