README.md

This project has been archived

I will not be maintaining this project, and recommend using router5 directly instead.

apollo-router5

Router5 integration with Apollo Client. Based on redux-router5. Using router5 with apollo may remove the need to include router5-listeners.

Requirements

• router5 >= 7.0.1
• apollo-client >= 2.5.0

How to use

• Create and configure your router instance.
• Create and configure your ApolloClient instance including routerResolvers and routerDefaults.
• Inject your router instance to apollo-router5.
• Add apolloPlugin to your router instance.
• Use the provided mutations to perform routing, and/or use your router instance directly.

// index.js
import createRouter from 'src/router/create-router';
import { apolloPlugin, injectRouterToApollo } from 'apollo-router5';
import client from 'src/apollo/apollo-client';

const router = createRouter();
injectRouterToApollo(router);
router.usePlugin(apolloPlugin);
router.setDependency('ApolloClient', client);
router.start();

injectRouterToApollo gives the routerResolvers from apollo-router5 access to your router instance so it can translate mutations into router5 method calls (e.g. translates the navigateTo mutation to router.navigate(...)).

apolloPlugin creates a router5 plugin that calls mutations to keep your apollo state in sync with your router. You must call router.setDependency('ApolloClient', client) to give apolloPlugin access to your client so it can execute mutations.

You need to include routerResolvers and routerDefaults when configuring apollo-client:

// apollo-client.js
import ApolloClient from 'apollo-boost';
import { routerResolvers, routerDefaults } from 'apollo-router5';
import { yourDefaults, yourResolvers } from './resolvers';

const client = new ApolloClient({
    clientState: {
        defaults: {
            ...routerDefaults,
            ...yourDefaults,
        },
        resolvers: yourResolvers
    }
});

client.addResolvers(routerResolvers);

export default client;

Note: You may need @babel/plugin-proposal-object-rest-spread to use the syntax shown above.

Apollo Schema

The following schema is used in your local apollo state, starting with Router5_Properties under the graphql field router:

type Router5_Properties {
    route: Router5_Route
    previousRoute: Router5_Route
    transitionRoute: Router5_Route
    transitionError: Router5_Error
}

type Router5_Error {
    code: String!
    segment: String
    error: String
}

type Router5_Route {
    name: String!
    path: String!
    params: String!
    meta: String!
}

The params and meta fields in the schema are JSON strings (from calling JSON.stringify() on the data from router5). I wasn't sure how else to make this accessible through graphql given the dynamic nature of the data in these fields. If you have a suggestion for a better approach, please let me know or open an issue!

An example query:

{
    router @client {
        route {
            name
            path
        }
    }
}

Mutations

You can use your router instance directly, and/or use these mutations exported from apollo-router5:

• navigateTo($name: String!, $params: Router5_Params, $opts: Router5_Opts)
• cancelTransition
• clearErrors
• canActivate($name: String!, $canActivate: Boolean!)
• canDeactivate($name: String!, $canDeactivate: Boolean!)

Router5_Params and Router5_Opts are objects of whatever shape you want. They should not be JSON strings, unlike when querying (as mentioned under Apollo Schema above).

// MyComponent.js
import { mutations } from 'apollo-router5';
import { graphql } from 'react-apollo';

export default graphql(mutations.navigateTo,{
    props: ({ mutate }) => ({
        navigateTo: name => mutate({ variables: { name } }),
    }),
})(MyComponent),

// Inside MyComponent, call this.props.navigateTo('myroute');

Integration with React

To reduce boilerplate and provide the route as a prop to your React components, you could use a HOC such as the following:

// withRoute.js
import { graphql } from 'react-apollo';
import gql from 'graphql-tag';

const query = gql`
    {
        router @client {
            route {
                name
                path
                params
                meta
            }
        }
    }
`;

export default graphql(query, {
    props: (props) => {
        const r = props.data.router.route;
        let route = null;
        if (r) {
            // Create new object to avoid modifying object from Apollo's cache.
            route = {};
            route.name = r.name;
            route.path = r.path;
            route.params = JSON.parse(r.params);
            route.meta = JSON.parse(r.meta);
        }
        return { route };
    },
});

Using it on MyComponent:

// MyComponent.js
import withRoute from './withRoute';

export default withRoute(MyComponent);

createRouteNodeSelector

I haven't created an equivalent of createRouteNodeSelector from redux-router5 yet. Please open an issue if this would be valuable to you. I haven't built anything with redux-router5 and I'm still in the early stages of the app I created apollo-router5 for, so I haven't had need of it yet.