Contributing

• Stars on GitHub: If you're a refine user and enjoy using our platform, don't forget to star it on GitHub! 🌟
• Improve documentation: Good documentation is imperative to the success of any project. You can make our documents the best they need to be by improving their quality or adding new ones.
• Give feedback: We're always looking for ways to make refine better, please share how you use refine, what features are missing and what is done good via GitHub Discussions or Discord.
• Share refine: Help us reach people. Share refine repository with everyone who can be interested.
• Contribute to codebase: your help is needed to make this project the best it can be! You could develop new features or fix existing issues - every contribution will be welcomed with great pleasure!

refine is a monorepo. For a monorepo, commit messages are essential to keep everything clear. We use conventional commits to keep our commit messages consistent and easy to understand.

<type>(optional scope): <description>

Examples:

• feat: allow provided config object to extend other configs
• fix: array parsing issue when multiple spaces were contained in string
• docs: correct spelling of CHANGELOG

• next – contains next version (1.x.0), most likely you would want to create a PR to this branch
• master – current stable version

Changesets are designed to make your workflows easier, by allowing the person making contributions to make key decisions when they are making their contribution. Changesets hold two key bits of information: a version type (following semver), and change information to be added to a changelog.

Follow the steps below to create a changeset:

npm run changeset

After that you need to,

• select the package(s) you are modifying
• choose one of major/patch/minor according to your change
• some explanation about the changes

and then you are done!

node version 16 is required.

This project has multiple packages and uses Lerna to manage packages under packages/.

First, install dependencies:

npm install

From now on, depending on the packages you plan to work on, (they are located under packages/ and examples/ directories - see lerna.json) you will need to bootstrap them and start them in watch mode. Instead of running lerna bootstrap directly, read on to see how refine team handles it.

Refer to lerna docs to learn more about it. →

Refer to lerna docs to learn more about lerna bootstrap. →

You can either bootstrap all packages or only the packages you plan to work on.

To bootstrap all packages (all packages under /examples and under /packages whose names start with @pankod/refine*), you should run:

npm run bootstrap

To bootstrap the specific packages/examples only (all packages under /packages whose names start with @pankod/refine* and specified packages):

npm run bootstrap -- --scope refine-use-select-example

Refer to lerna docs to learn more about scope flag. →

npm run bootstrap command bootstraps all packages whose name start with @pankod/refine* and all packages under /examples. If you add filters with --scope flag, you can avoid bootstrapping all packages under /examples.

At this point, all/required packages are bootstrapped. Now you can start the packages you plan to work on in development mode. If you don't want to start all packages in development mode, you should filter them:

npm run build
npm run start -- --scope @pankod/refine-core --scope @pankod/refine-antd --scope refine-use-select-example

This command starts the example named refine-use-select-example in dev mode. The value of the flag --scope is the name that is defined in it's package.json file. Note that --scope flag should be used for every package that should be filtered. If you should start two packages:

Now all filtered packages are running in watch mode. They should re-compile when you make a change in any of them.

Our documentation is built with Docusaurus. To start it in development mode, run:

cd documentation
npm install
DISABLE_DOCGEN=true npm run start

INCLUDED_PACKAGES=antd,core npm run start

<PropsTable module="@pankod/refine-antd/Create" />

npm run test command runs tests for all packages. If you're working on a package (e.g. /packages/core), you can run tests only for that package:

cd packages/core
npm run test

Or you can do it for a specific file:

npm run test -- /src/hooks/export/index.spec.ts

Also, to run a specific file's tests in watch mode:

npm run test -- --watch /src/hooks/export/index.spec.ts

Get coverage report for that file:

npm run test -- --coverage /src/hooks/export/index.spec.ts

When you run the command that produces coverage report, go to /coverage/lcov-report/index.html file to see coverage results. If you run this command in /packages/core directory, then coverage report will be generated in /packages/core/coverage.

Please make sure you contribute well tested code.

We're using live previews powered with react-live to demonstrate our components and logic with refine running at full functionality. To create a live preview, you should add live property to your code blocks in markdown files.

You can use the following properties to adjust your live blocks:

There are two ways to hide/show code sections in your live code blocks; either you can wrap your visible code to // visible-block-start and // visible-block-end comments, or you can use // hide-next-line, // hide-start and // hide-end comments. You can use both of them in the same code block.

// visible-block-start and // visible-block-end

This wrapper can be used to show only the desired part of the code in the code block and will not affect the live preview. Copy code button will only copy the code inside this block. This is the recommended way to hide boilerplate/unwanted code.

// hide-next-line and // hide-start and // hide-end

These magic comments will hide the next line or the wrapped code block. You can use these to hide the code that you want to show in the code blocks. These will also not affect the live preview but those lines will be copied with the copy button. Use these to hide the required code pieces for the live preview but are out of scope for the example. Such as while showing how a property of a component works in live preview, you can hide the required but not relevant props.

To render the live preview you should call the render function with your component. render function is specific to react-live and it will render the preview in the browser; therefore not needed to be visible in the codeblock, it's recommended to leave the render part outside of the // visible-block wrapper.

Example Usage

```tsx live hideCode url=http://localhost:3000/posts/create
// You can use object destructuring to import the necessary functions and components which you don't want to show in the code block.
const { CreateButton } = RefineAntd;

interface ICategory {
id: number;
title: string;
}

interface IPost {
id: number;
title: string;
content: string;
status: "published" | "draft" | "rejected";
category: { id: number };
}

// visible-block-start
// Import statements will be replaced with the object destructuring but visible code block will not be affected.
import {
    Create,
    Form,
    Input,
    Select,
    useForm,
    useSelect,
} from "@pankod/refine-antd";

const PostCreate: React.FC = () => {
const { formProps, saveButtonProps } = useForm<IPost>();

    const { selectProps: categorySelectProps } = useSelect<ICategory>({
        resource: "categories",
    });

    return (
        <Create saveButtonProps={saveButtonProps}>
            <Form {...formProps} layout="vertical">
                <Form.Item
                    label="Title"
                    name="title"
                    rules={[
                        {
                            required: true,
                        },
                    ]}
                >
                    <Input />
                </Form.Item>
                <Form.Item
                    label="Category"
                    name={["category", "id"]}
                    rules={[
                        {
                            required: true,
                        },
                    ]}
                >
                    <Select {...categorySelectProps} />
                </Form.Item>
                <Form.Item
                    label="Status"
                    name="status"
                    rules={[
                        {
                            required: true,
                        },
                    ]}
                >
                    <Select
                        options={[
                            {
                                label: "Published",
                                value: "published",
                            },
                            {
                                label: "Draft",
                                value: "draft",
                            },
                            {
                                label: "Rejected",
                                value: "rejected",
                            },
                        ]}
                    />
                </Form.Item>
            </Form>
        </Create>
    );

};
// visible-block-end

// This part is required to render the preview.
render(
    <RefineAntdDemo
        initialRoutes={["/posts/create"]}
        resources={[
            {
                name: "posts",
                list: () => (
                    <div>
                        <p>This page is empty.</p>
                        <CreateButton />
                    </div>
                ),
                create: PostCreate,
            },
        ]}
    />,
);
```;

Result

// Import statements will be replaced with the object destructuring but visible code block will not be affected.
import {
    Create,
    Form,
    Input,
    Select,
    useForm,
    useSelect,
} from "@pankod/refine-antd";

const PostCreate: React.FC = () => {
    const { formProps, saveButtonProps } = useForm<IPost>();

    const { selectProps: categorySelectProps } = useSelect<ICategory>({
        resource: "categories",
    });

    return (
        <Create saveButtonProps={saveButtonProps}>
            <Form {...formProps} layout="vertical">
                <Form.Item
                    label="Title"
                    name="title"
                    rules={[
                        {
                            required: true,
                        },
                    ]}
                >
                    <Input />
                </Form.Item>
                <Form.Item
                    label="Category"
                    name={["category", "id"]}
                    rules={[
                        {
                            required: true,
                        },
                    ]}
                >
                    <Select {...categorySelectProps} />
                </Form.Item>
                <Form.Item
                    label="Status"
                    name="status"
                    rules={[
                        {
                            required: true,
                        },
                    ]}
                >
                    <Select
                        options={[
                            {
                                label: "Published",
                                value: "published",
                            },
                            {
                                label: "Draft",
                                value: "draft",
                            },
                            {
                                label: "Rejected",
                                value: "rejected",
                            },
                        ]}
                    />
                </Form.Item>
            </Form>
        </Create>
    );
};