Integrate refine with existing project

[barrynerd]

Hi all -

My question is probably something others besides me would like to know, so I hope someone will help me here.

I am starting a nextjs project. There are two boilerplates I like, the first has a lot of dev environment stuff already installed and a basic app. The second is superplate with refine (and for learning, the default data). I am mostly agnostic as to theme, for now Material UI is my choice, could go headless with Tailwind eventually. Using basic rest api to access data. Probably will use mongodb, but might go with a graphql db.

What I am looking at is how to integrate refine with the the other boilerplate (which works fine on its own). The alternate is to do it the other way around, but I think this way might be easier.

what I am looking for is something like "npm create refine-app@latest" which asks the right questions for me without all the parts of superplate I don't need, but I am concerned about overwriting files. I can use git branches to merge if I have to, I suppose, but that seems like I would want to avoid it if I can.

I looked for tutorials via google that address this issue, but the only thing I found was in the refine documentation that says you can add refine to an existing project, but doesn't say how.

Any guidance would be appreciated, thanks everyone!

[vinclou]

Hi all -

My question is probably something others besides me would like to know, so I hope someone will help me here.

I am starting a nextjs project. There are two boilerplates I like, the first has a lot of dev environment stuff already installed and a basic app. The second is superplate with refine (and for learning, the default data). I am mostly agnostic as to theme, for now Material UI is my choice, could go headless with Tailwind eventually. Using basic rest api to access data. Probably will use mongodb, but might go with a graphql db.

What I am looking at is how to integrate refine with the the other boilerplate (which works fine on its own). The alternate is to do it the other way around, but I think this way might be easier.

what I am looking for is something like "npm create refine-app@latest" which asks the right questions for me without all the parts of superplate I don't need, but I am concerned about overwriting files. I can use git branches to merge if I have to, I suppose, but that seems like I would want to avoid it if I can.

I looked for tutorials via google that address this issue, but the only thing I found was in the refine documentation that says you can add refine to an existing project, but doesn't say how.

Any guidance would be appreciated, thanks everyone!

'Short Answer:' Just add the bare minimum Refine deps to the template of your choice, then customise the Refine wrapper to your liking.

'Long Answer:' Not a Refine team member, but what you have described would be very hard for Refine team to achieve just because of a mere use cases for it out there. What I've ended up doing for my team for our refactor was take their base template and manually install npm packages I wanted running on top of Vite / this included setting up all the custom providers described in the docs; And everything was pretty much custom as we wanted an easy migration without rewriting too much of components just the data layer was primarily the target + codebase structure and utils. And all of this is running on top of C# server in parallel with the old app. Depending on your experience this should be a day of work for a starter clean project if u don't tinker with ur eslint, never touch that monster if it works.

[aliemir]

@vinclou thank you for the answer and sharing your experience with refine 🙏 We'd love to hear more about your experience about refine and your integration process, let me know if you're interested 🚀

[vinclou]

@aliemir Yeah, no problem we can sync through socials, just tell me the preferred way to go about it 👍

[aliemir]

Hey @barrynerd, you can use refine with an existing project or from scratch with no issues. npm create refine-app provides bunch of prompts and templates to get you started but those implementations also have their own tutorials/documentations in https://refine.dev/docs

Let me share our Next.js docs that you can follow to integrate refine with your existing project. https://refine.dev/docs/advanced-tutorials/ssr/nextjs/

1. To use refine, you need @pankod/refine-core which we export the <Refine/> component.
2. We also need you to set up the router provider, in your case its @pankod/refine-nextjs-router
3. You'll also need the data provider, if you're going to use a REST API, I suggest you to start with @pankod/refine-simple-rest, if you want to extend and customize this for your own needs, you can do swizzle later (from @pankod/refine-cli)
4. You can use @pankod/refine-mui but the documentation is done with @pankod/refine-antd but there will be no difference for the setup. Or you can just skip the UI Packages and go headless. (props like Layout, Sider, etc. is not required but optional)

You can always check out our examples in your local or from stackblitz (a list can be seen at https://refine.dev/docs/examples/ but not limited to the list, you can find more examples in our repo). Documentation and the examples will help you complete your setup and use refine.

There will be changes in the way we initialize refine in our next major release to make it easier to integrate refine. (won't be breaking the existing apps). We'll make the routerProvider not required and refine will not depend on its existence. 🙏

Note

We're updating our tutorials so hopefully we'll provide a easy to follow and understand content to let everyone start using refine from scratch or from an existing project. 🙏

[barrynerd]

Thanks everyone for prompt guidance so far. I will use it to do some experiments. If I have more questions, may I post them here, or should I open a new issue?

As for my experience, this is my first complex nextjs project, but otherwise I am very experienced in developing and refactoring code, so this should be doable for me.

If I get it to work, I will provide a report here for others to find.

[barrynerd]

I just tried (successfully) to build with superplate/material UI and unsuccessfully for a merged boilerplate followed by npm create refine-app@latest -- -o refine-nextjs barry02

when I run npm run dev in barry02 I get a lot of errors, the gist of which seems to be that there are missing modules.

I ran npm run refine update and installed the modules that appeared to be missing, but it still returns the same errors on npm run dev

Here is a comparison npm list on the two projects. I feel like something is missing, but I am not sure exactly which differences here are refine-related.

superplate06@0.1.0
├── @mui/icons-material@5.11.0
├── @pankod/refine-cli@1.15.0
├── @pankod/refine-core@3.94.0
├── @pankod/refine-inferencer@2.0.2
├── @pankod/refine-mui@3.61.2
├── @pankod/refine-react-hook-form@3.37.2
├── @pankod/refine-react-router-v6@3.38.0
├── @pankod/refine-simple-rest@3.37.4
├── @testing-library/jest-dom@5.16.5
├── @testing-library/react@11.2.7
├── @testing-library/user-event@12.8.3
├── @types/jest@26.0.24
├── @types/node@12.20.55
├── @types/react-dom@18.0.10
├── @types/react@18.0.26
├── react-dom@18.2.0
├── react-scripts@5.0.1
├── react@18.2.0
├── typescript@4.9.4
└── web-vitals@1.1.2

2$ npm list
barry02@0.1.0
├── @pankod/refine-antd@4.7.0
├── @pankod/refine-cli@1.15.0
├── @pankod/refine-core@3.94.0
├── @pankod/refine-inferencer@2.0.2
├── @pankod/refine-nextjs-router@4.1.0
├── @pankod/refine-simple-rest@3.37.4
├── @types/node@14.18.36
├── @types/react-dom@18.0.10
├── @types/react@18.0.26
├── @typescript-eslint/parser@4.33.0
├── cross-env@7.0.3
├── next-compose-plugins@2.2.1
├── next@13.1.1
├── react-dom@18.2.0
├── react@18.2.0
├── tailwindcss@3.2.4
└── typescript@4.9.4

I feel like I am pretty close here! If I can get it to start up and show the fake data, I will be very happy. I am not concerned right now about antd vs material ui, I just want to see it run at this stage. Eventually I will probably go headless with tailwindcss anyway (although I am open to reasons NOT to do that from those with more nextjs experience than me, which is everyone here I am sure)

Thanks again for your guidances!

[aliemir]

Hey @barrynerd, I'll come up with a step-by-step integration following this comment as soon as possible to get you started with no errors 😅

[aliemir]

I've created a new next.js app without refine with the following command

npm create next-app@latest my-app

Let's make this our starting point, if you're using a custom template or anything it should not change the steps below.

Installing refine packages

I'm adding @pankod/refine-core, @pankod/refine-nextjs-router and @pankod/refine-simple-rest for the basic setup.

npm i @pankod/refine-core@latest @pankod/refine-nextjs-router@latest @pankod/refine-simple-rest@latest

Setting up refine in pages/_app.tsx

Our current _app.tsx file is this;

import '../styles/globals.css'
import type { AppProps } from 'next/app'

export default function App({ Component, pageProps }: AppProps) {
  return <Component {...pageProps} />
}

Let's add our import of <Refine>

import "../styles/globals.css";
import type { AppProps } from "next/app";
+ import { Refine } from "@pankod/refine-core";

export default function App({ Component, pageProps }: AppProps) {
  return (
+    <Refine>
      <Component {...pageProps} />
+    </Refine>
  );
}

Now we need to add our dataProvider

import "../styles/globals.css";
import type { AppProps } from "next/app";
import { Refine } from "@pankod/refine-core";
+ import dataProvider from "@pankod/refine-simple-rest";

+ const API_URL = "https://api.fake-rest.refine.dev";

export default function App({ Component, pageProps }: AppProps) {
  return (
+    <Refine dataProvider={dataProvider(API_URL)}>
      <Component {...pageProps} />
    </Refine>
  );
}

Now it's time to integrate with the Next.js and its router.

import "../styles/globals.css";
import type { AppProps } from "next/app";
import { Refine } from "@pankod/refine-core";
import dataProvider from "@pankod/refine-simple-rest";
+ import routerProvider from "@pankod/refine-nextjs-router";

const API_URL = "https://api.fake-rest.refine.dev";

export default function App({ Component, pageProps }: AppProps) {
  return (
    <Refine
      dataProvider={dataProvider(API_URL)}
+      routerProvider={routerProvider}
    >
      <Component {...pageProps} />
    </Refine>
  );
}

Setting up the refine resource routes

We're now finished with the initial setup of _app.tsx, let's create a file pages/[[...refine]].tsx to make refine render our resource routes. While adding our [[...refine]].tsx page, we need to remove the index.tsx file for the / path, since they have the same specificity, Next.js will throw an error while using both. For your case, you might not even need the [[...refine]].tsx route if you're going to use a file based routing but you can still use file based routing and keep the [[...refine]].tsx as a fallback, it will not have any conflicts with your pages in sub directories.

import { NextRouteComponent } from "@pankod/refine-nextjs-router";

export default NextRouteComponent;

Now we're done with the Next.js setup, let's add a sample resource and a list view.

Having the sample views and generating the sample code from the inferencer

We can add @pankod/refine-inferencer to create a view for us with the resource. (Currently, we don't have inferencer for the headless but it's in progress. as a substitute let's add @pankod/refine-antd dependency to have a sample view with them. (Optional of course, if you don't want to use inferencer and the other packages, you can just pass simple components to your resources.)

npm i @pankod/refine-inferencer @pankod/refine-antd dayjs

And update our _app.tsx with resources prop to <Refine>

import "../styles/globals.css";
import type { AppProps } from "next/app";
import { Refine } from "@pankod/refine-core";
import dataProvider from "@pankod/refine-simple-rest";
import routerProvider from "@pankod/refine-nextjs-router";
+ import { AntdInferencer } from "@pankod/refine-inferencer/antd";

const API_URL = "https://api.fake-rest.refine.dev";

export default function App({ Component, pageProps }: AppProps) {
  return (
    <Refine
      dataProvider={dataProvider(API_URL)}
      routerProvider={routerProvider}
+      resources={[
+        {
+          name: "products",
+          list: AntdInferencer,
+          show: AntdInferencer,
+        },
+      ]}
    >
      <Component {...pageProps} />
    </Refine>
  );
}

Since we've added @pankod/refine-antd, we can use its layout to make it look better 😅

import "../styles/globals.css";
import type { AppProps } from "next/app";
import { Refine } from "@pankod/refine-core";
import dataProvider from "@pankod/refine-simple-rest";
import routerProvider from "@pankod/refine-nextjs-router";
import { AntdInferencer } from "@pankod/refine-inferencer/antd";
+ import {
+  Layout,
+  notificationProvider,
+  ErrorComponent,
+ } from "@pankod/refine-antd";

const API_URL = "https://api.fake-rest.refine.dev";

export default function App({ Component, pageProps }: AppProps) {
  return (
    <Refine
      dataProvider={dataProvider(API_URL)}
      routerProvider={routerProvider}
      resources={[
        {
          name: "products",
          list: AntdInferencer,
          show: AntdInferencer,
        },
      ]}
+      notificationProvider={notificationProvider}
+      Layout={Layout}
+      catchAll={<ErrorComponent />}
    >
      <Component {...pageProps} />
    </Refine>
  );
}

Let's see some results;

/ route will redirect to the first resource and its /samples

And our /samples/list/:id path will look like this,

That's it with the integration. If you want to use @pankod/refine-cli (It will give you a nice experience with its update helper and update checkers also we have the swizzle command to let you customize the components easily by exporting them from the source code)

Here's the docs for it, if you want to integrate with it too https://refine.dev/docs/packages/documentation/cli/#how-to-add-to-an-existing-project

For more info about the Next.js setup and more here's our Next.js docs https://refine.dev/docs/advanced-tutorials/ssr/nextjs/

You can always refer to our docs and if you're having issues, you can reach out from Github or our discord channel https://discord.gg/refine 🚀 🚀

[aliemir]

Hope this helps @barrynerd 🙏

[barrynerd]

The manual part of this appears to have worked great, thank you so much for your effort to help. I really appreciate it, now I am at a point where I have a basic functioning system and I can play around further.

The only comment I would as is that the routes/urls you gave for the sample data are slightly different from what I see: where you have "sample", I have "product", and where you have "list", I have "show".

I am very grateful for the prompt and thorough response. You never know about that with new projects, and this has saved me a ton of trouble in my evaluation of refine. I am very excited about the inferencer so that I can minimize CRUD work, because I anticipate I will have a lot of it, even for my product proof of concept.

[aliemir]

Oops, my bad 🤦 I've also used products resource but wrote samples in the comment 😅 (and also list instead of show)

You're right, the urls for the specified resource products in the screenshots are /products and /products/show/:id

[barrynerd]

Thanks! I look forward to it.

…

On Thu, Jan 5, 2023, 1:10 AM Ali Emir Şen ***@***.***> wrote: Hey @barrynerd <https://github.com/barrynerd>, I'll come up with a step-by-step integration following this comment as soon as possible to get you started with no errors 😅 — Reply to this email directly, view it on GitHub <#3343 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACAR66DCBDYUG57KCMS5I3LWQ2FXZANCNFSM6AAAAAATQHY4OY> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[barrynerd]

This looks excellent, I'll give both the manual and cli versions a spin and report back.

…

On Thu, Jan 5, 2023, 5:18 AM Ali Emir Şen ***@***.***> wrote: Hope this helps @barrynerd <https://github.com/barrynerd> 🙏 — Reply to this email directly, view it on GitHub <#3343 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACAR66F4ZZ3XUEVI5CXHONLWQ3C2HANCNFSM6AAAAAATQHY4OY> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[barrynerd]

I am posting this here first rather than as an issue because I am not sure if it is user error (meaning me), an issue with refine, or an issue with antd.

I have set up a project as instructed above and it works fine. I have replaced the data provider with my own json-server on local host and am proceeding to experiment from there.

This is not critical to moving ahead as I have a workaround, but it would he helpful for either me to know my error, or for me to report a bug appropriately to the responsible developers.

What I notice is that when I have a server running via "npm run dev", the css cascade on the background color on ant-button-primary class (such as on the create form) is left as transparent, and thus nearly invisible except for the box shadow:

button, [type='button'], [type='reset'], [type='submit'] {
-webkit-appearance: button;
background-color: transparent;
background-image: none;
}

:where(.css-dev-only-do-not-override-k83k30).ant-btn-primary {
color: #fff;
background-color: #1677ff;
box-shadow: 0 2px 0 rgba(5, 145, 255, 0.1);
}

My workaround is to place a rule in global.css:

button.ant-btn.ant-btn-primary {
background: #1677ff;
}

Am I missing something here, or is this a bug? If a bug, which module is it?

[yildirayunlu]

I am unable to reproduce this problem. If you can post a stackblitz or codesandbox project we will do our best to fix the problem. Also, for antd5, I recommend you to review the following document.

https://ant.design/docs/react/customize-theme

[vinclou]

Sounds like an AntD configuration problem to me, make sure you follow the AntD setup guidelines:

I remember having a problem with styles being applied funky, but I don't remember why exactly this solved the problem, this might work for you.

import './styles/index.css'
import './styles/vars.css'
// Order of style injection is important here to avoid style overrides, preflight: false -> can be used in tailwind config as well
import '@pankod/refine-antd/dist/styles.min.css'