Home

Awesome

@marcantoine/ra-data-graphql-prisma

NPM

react-admin data provider for Prisma (v1)

The package is a fork from https://github.com/Weakky/ra-data-opencrud which includes some non-supported features.

It has then been improved and stabilized by a downstream fork https://github.com/unly/ra-data-opencrud

The only difference to date between this fork and the downstrem fork is a fix on Date: An empty date is not supported by Prisma v1. This package transform now a "" date to null. This has been made necessary by an update to Material-UI and react-admin.

This package is currently used in production on a private react-admin app.

Legacy readme from downstream:

Status: STABLE - NON-MAINTAINED

This package has been released under v1.0.0 version and is considered stable.

Note that we do not intend on maintaining it. Issues are open for questions but do not expect bug fixes.

As of April 2020, this package is probably the most advanced of all forks created from https://github.com/Weakky/ra-data-opencrud and can be used to build your own fork.

Overview of changes

See CHANGELOG

Basically, this package has improved TS support, fixed Jest tests and added more features for nested relationships, image upload, and more, compared to it's upstream origin.

Also, it's used in a live demo and allows you to get started quickly with react-admin.

Live demo

Why again another fork?

Our motivations

We wanted to build our own admin backoffice to manage our content. But the task has revealed itself much more complicated than what I thought it'd be.

A bit of history...

Why use this one?

<!-- toc --> <!-- tocstop -->

What is react admin ? And what's @unly/ra-data-graphql-prisma ?

Find out more about the benefits of using react-admin with Prisma here.

Prisma V1 offers a full graphQL CRUD Server out of the box. This module allows to use react-admin directly on Prisma Server.

This module is a fork of ra-data-graphql-prisma, itself a fork of ra-data-opencrud.

Since ra-data-opencrud maintainer focus on the future of back-end development with Prisma Framework (v2) and nexus-prisma, this fork allow us to maintain and fix some part of the module.

While the original module goal was to follow the opencrud specification, this fork mostly focus on Prisma 1. The module should however with other server following the opencrud convention.

This module is not compatible with Prisma (2) Framework & nexus-prisma.

Installation

Install with:

npm install --save graphql @unly/ra-data-graphql-prisma

or

yarn add graphql @unly/ra-data-graphql-prisma

Usage

This example assumes a Post type is defined in your datamodel. It's based on create-react-app.

// in App.js
import React, { Component } from 'react';
import buildGraphQLProvider from '@unly/ra-data-graphql-prisma';
import { Admin, Resource, Delete } from 'react-admin';

import { PostCreate, PostEdit, PostList } from './posts';

const client = new ApolloClient();

class App extends Component {
    constructor() {
        super();
        this.state = { dataProvider: null };
    }
    componentDidMount() {
        buildGraphQLProvider({ clientOptions: { uri: 'your_prisma_or_graphcms_endpoint' }})
            .then(dataProvider => this.setState({ dataProvider }));
    }

    render() {
        const { dataProvider } = this.state;

        if (!dataProvider) {
            return <div>Loading</div>;
        }

        return (
            <Admin dataProvider={dataProvider}>
                <Resource name="Post" list={PostList} edit={PostEdit} create={PostCreate} remove={Delete} />
            </Admin>
        );
    }
}

export default App;

And that's it, buildGraphQLProvider will create a default ApolloClient for you and run an introspection query on your Prisma/GraphCMS endpoint, listing all potential resources.

Options

Relation and references

In order to link to reference record using ReferenceField or ReferenceInput, @unly/ra-data-graphql-prisma uses a object notation (instead of snake_case or camelCase as seen in the react-admin documentation)

<ReferenceInput source="company.id" reference="Company">
    <SelectInput optionText="id" />
</ReferenceInput>

Exception : The reference in a ReferenceArrayField is with camelCase : this field has not been managed yet.

Customize the Apollo client

You can either supply the client options by calling buildGraphQLProvider like this:

buildGraphQLProvider({ clientOptions: { uri: 'your_prisma_or_graphcms_endpoint', ...otherApolloOptions } });

Or supply your client directly with:

buildGraphQLProvider({ client: myClient });

Overriding a specific query

The default behavior might not be optimized especially when dealing with references. You can override a specific query by decorating the buildQuery function:

With a whole query

// in src/dataProvider.js
import buildGraphQLProvider, { buildQuery } from '@unly/ra-data-graphql-prisma';

const enhanceBuildQuery = introspection => (fetchType, resource, params) => {
    const builtQuery = buildQuery(introspection)(fetchType, resource, params);

    if (resource === 'Command' && fetchType === 'GET_ONE') {
        return {
            // Use the default query variables and parseResponse
            ...builtQuery,
            // Override the query
            query: gql`
                query Command($id: ID!) {
                    data: Command(id: $id) {
                        id
                        reference
                        customer {
                            id
                            firstName
                            lastName
                        }
                    }
                }`,
        };
    }

    return builtQuery;
}

export default buildGraphQLProvider({ buildQuery: enhanceBuildQuery })

Or using fragments

You can also override a query using the same API graphql-binding offers.

buildQuery accept a fourth parameter which is a fragment that will be used as the final query.

// in src/dataProvider.js
import buildGraphQLProvider, { buildQuery } from '@unly/ra-data-graphql-prisma';

const enhanceBuildQuery = introspection => (fetchType, resource, params) => {
    if (resource === 'Command' && fetchType === 'GET_ONE') {
        // If you need auto-completion from your IDE, you can also use gql and provide a valid fragment
        return buildQuery(introspection)(fetchType, resource, params, `{
            id
            reference
            customer { id firstName lastName }
        }`);
    }

    return buildQuery(introspection)(fetchType, resource, params);
}

export default buildGraphQLProvider({ buildQuery: enhanceBuildQuery })

As this approach can become really cumbersome, you can find a more elegant way to pass fragments in the example under /examples/prisma-ecommerce

Customize the introspection

These are the default options for introspection:

const introspectionOptions = {
    include: [], // Either an array of types to include or a function which will be called for every type discovered through introspection
    exclude: [], // Either an array of types to exclude or a function which will be called for every type discovered through introspection
}

// Including types
const introspectionOptions = {
    include: ['Post', 'Comment'],
};

// Excluding types
const introspectionOptions = {
    exclude: ['CommandItem'],
};

// Including types with a function
const introspectionOptions = {
    include: type => ['Post', 'Comment'].includes(type.name),
};

// Including types with a function
const introspectionOptions = {
    exclude: type => !['Post', 'Comment'].includes(type.name),
};

Note: exclude and include are mutually exclusives and include will take precedence.

Note: When using functions, the type argument will be a type returned by the introspection query. Refer to the introspection documentation for more information.

Pass the introspection options to the buildApolloProvider function:

buildApolloProvider({ introspection: introspectionOptions });

Tips and workflow

Performance issues

As react-admin was originally made for REST endpoints, it cannot always take full advantage of GraphQL's benefits.

Although react-admin already has a load of built-in optimizations (Read more here and here), it is not yet well suited when fetching n-to-many relations (multiple requests will be sent).

To counter that limitation, as shown above, you can override queries to directly provide all the fields that you will need to display your view.

Suggested workflow

As overriding all queries can be cumbersome, this should be done progressively.

Contributing

Use the example under examples/prisma-ecommerce as a playground for improving @unly/ra-data-graphql-prisma.

To easily enhance @unly/ra-data-graphql-prisma and get the changes reflected on examples/prisma-ecommerce, do the following:

Once this is done, the @unly/ra-data-graphql-prisma dependency will be replaced by the one on the repository. One last thing, don't forget to transpile the library with babel by running the following command on the root folder

yarn watch

You should now be good to go ! Run the tests with this command:

jest

Known issues

Yarn install error on fsevent

When installing a local environment using yarn and a node version > 10, a problem might occurs while installing some dependencies (fsevent). Running the following command appears to fix the problem

yarn cache clean && yarn upgrade && yarn

Related issues : https://github.com/yarnpkg/yarn/issues/3926

Contributing

We gladly accept PRs, but please open an issue first so we can discuss it beforehand.

Working locally

yarn start # Shortcut - Runs linter + build + tests in concurrent mode (watch mode)

OR run each process separately for finer control

yarn lint
yarn build
yarn test

Test

yarn test # Run all tests, interactive and watch mode
yarn test:once
yarn test:coverage

Versions

SemVer

We use Semantic Versioning for this project: https://semver.org/. (vMAJOR.MINOR.PATCH: v1.0.1)

Releasing and publishing

yarn releaseAndPublish # Shortcut - Will prompt for bump version, commit, create git tag, push commit/tag and publish to NPM

yarn release # Will prompt for bump version, commit, create git tag, push commit/tag
npm publish # Will publish to NPM

Don't forget we are using SemVer, please follow our SemVer rules.

Pro hint: use beta tag if you're in a work-in-progress (or unsure) to avoid releasing WIP versions that looks legit

Changelog

Our API change (including breaking changes and "how to migrate") are documented in the Changelog.

See changelog

License

MIT

Vulnerability disclosure

See our policy.

Contributors and maintainers

This project is being maintained by:

[ABOUT UNLY] <a href="https://unly.org"><img src="https://storage.googleapis.com/unly/images/ICON_UNLY.png" height="40" align="right" alt="Unly logo" title="Unly logo" /></a>

Unly is a socially responsible company, fighting inequality and facilitating access to higher education. Unly is committed to making education more inclusive, through responsible funding for students. We provide technological solutions to help students find the necessary funding for their studies. We proudly participate in many TechForGood initiatives. To support and learn more about our actions to make education accessible, visit :

Tech tips and tricks from our CTO on our Medium page!

#TECHFORGOOD #EDUCATIONFORALL