Guidelines for package authors

[gadicc]

Hey guys, absolutely epic work here! 👏 Can't believe how quickly everything has been put together, especially all the various integrations, etc.

One of the most awesome things about Meteor for me has always been how packages could rely on the full stack. But for the majority of cases, this really just amounted to having database access on the client and server (and routing, but we'll save that for another day).

I think it would be great to have some guidelines for package authors, even if they're pretty simple and obvious. The idea is that application developers will have a consistent experience in adding apollo-aware packages to their app. i.e.

npm install --save apollo-awesome apollo-admin

// client/lib/apollo-packages.js
import apolloClient from './apollo-client.js';

import Admin from 'apollo-admin';
import Awesome from 'apollo-awesome';

const admin = new Admin({ apolloClient });
const awesome = new Awesome({ apolloClient, and, other, options });

export { admin, awesome };

// server/lib/apollo-packages.js
import apolloServer from './apollo-server.js';
import Awesome from 'apollo-awesome';
const awesome = new Awesome({ apolloServer });
export { awesome };

And then for package authors, maybe something like:

import ApolloClient from 'apollo-client';

class Awesome {
  constructor({ apolloClient }) {
    if (!(apolloClient instanceof ApolloClient))
      throw new Error("awesome.init(options) expects options.apolloClient to be a valid ApolloClient instance");
    this.apolloClient = apolloClient;
  }
}

export default Awesome;

with guidelines / recommendations, i.e. Apollo packages should:

• Export a default class with a constructor(options) that takes an apolloClient or apolloServer
• Assert that said object is an instance of the respective class
• Include apollo-client/server as a peer dependency.

Like I said, this is may be quite simple and obvious, but I think a consistent and easy application developer experience will do wonders for quick and happy adoption.

The directory layout about could also be a recommendation for application developers, but they can do whatever makes sense for them, the main thing is that instantiating apollo packages is a consistent and natural experience.

[stubailo]

Wow this is a great idea! Can we get a list going of possible types of packages? I think that would help me think about the various guidelines that would be helpful!

[gadicc]

Glad it was well received. For an exhaustive list of examples you can:

$ echo "SELECT DISTINCT(packageName) FROM versions WHERE content LIKE '%mongo%';" \
  | sqlite3 ~/.meteor/package-metadata/v2.0.1/packages.data.db | grep -v errors

:)

I jotted down some thoughts in https://hackpad.com/Apollo-aware-NPM-packages-8XClPMNuBam; maybe others can help add to it.

[stubailo]

Very nice! Do you think there is something else we could use instead of Hackpad, like maybe the github wiki or a markdown file in this repo? I'd rather not have too many different places where files are scattered.

[gadicc]

Sure. I think the wiki is better, easier for people to edit, but I'm easy. I tried to go there now but it seems to just redirect to the main repo's URL. I think someone with commit access has to create the first page first. Maybe.

[stubailo]

@gadicc I made the wiki public and editable by anyone. Let's see how it goes!

[gadicc]

Cool :) https://github.com/apollostack/apollo/wiki/Brainstorm:-Apollo-aware-NPM-packages.

[stubailo]

Excellent! Let's keep this open for discussion. You can also join our slack team! http://slack.apollostack.com/

[pawelphilipczyk]

I was thinking about cms integrations and this looks to be something that could be huge. For example there is a discussion going on in Drupal community about going headless progressively or even fully. I could totally imagine a package like apollo-drupal or apollo-wordpress.

[stubailo]

Wow that would be awesome! Having a GraphQL API on top of Drupal would make it super easy to build frontend apps on it.

[batjko]

Those guys from Wordpress are becoming Node enthusiasts already, only a matter of time before they release a Wordpress server that's based on Node instead of PHP, making a GraphQL API even more attractive.

[helfer]

WordPress + GraphQL: https://github.com/ramsaylanier/WordPressExpress

[stubailo]

OMG using Apollo Client with a wordpress backend would be so cool.

[stubailo]

Note: I haven't done much about this topic yet, but hope to give integration packages a lot more thought in the next week!

[batjko]

WordPress + GraphQL: https://github.com/ramsaylanier/WordPressExpress

Love it!
The Automattic guys would be idiots not to work with this guy.
That project could probably benefit a lot from Apollo tools.

[ramsaylanier]

@stubailo I'm working on using Apollo with Wordpress in the next week or two to replace GraphQL + Relay in WordExpress!

Thanks for the words of encouragement!

[stubailo]

Amazing -- Excited to help answer any questions, and get bugs fixed if you run into anything!

If you're interested in SSR/Hydration, we have a project that @jbaxleyiii is starting up here: https://github.com/apollostack/react-router-apollo/issues/1

Does that sound like something you would need?

[jbaxleyiii]

@ramsaylanier let me know how I can help!

[ramsaylanier]

Yes absolutely @stubailo @jbaxleyiii - one of my biggest hurdles is getting SSR to work with Relay/GraphQL. This is pretty much a non-starter if I can't get it to work as SEO is huge requirement when working with WordPress (or any CMS really)

[jbaxleyiii]

@ramsaylanier same for us! 👍

[ramsaylanier]

so far I've just been able to replace the graphqlHTTP with apolloServer and started implementing and routes and stuff.

https://github.com/ramsaylanier/ApolloPress

[ramsaylanier]

So I've been able to completely replace Relay with Apollo in WordExpress and it works perfectly. I'm not use resolvers or connectors as per the Apollo documentation - I'm using GraphQL types manually but end result is the same.

I've made an npm module that easily connects to a WordPress database and provides a basic GraphQL schema. Check it out.

https://github.com/ramsaylanier/wordexpress-schema

[stubailo]

That's awesome! Is it possible to use Wordpress for just part of the schema and add extra data from a separate database? I am really excited about the possibility of having NPM packages that ship part of a schema, and can be used together to build a schema over multiple backends.

[ramsaylanier]

It is something I have thought about but have not tried. I think it would be pretty easy this way - you just have to modify the resolve functions when you are defining your GraphQL schema.

Yeah! I definitely wanted my basic WordPress schema to be extendable and I think I have achieved that goal - at least on a basic level.

[stubailo]

@ramsaylanier any place I can check out how you've used Apollo (the repo you linked seems to be from before)? Definitely want to learn how it went and what could be improved!

[ramsaylanier]

The ApolloPress repo is where I've been playing around with it - I havent updated the readme or anything. You might find this commit to be interesting and it shows pretty much how I replaced Relay with Connect.

[stubailo]

@ramsaylanier wow! How did you delete so much code?

[ramsaylanier]

Eh, parts of that commit are misleading - I had some duplicate schema stuff in the /data folder that I moved to a /schema folder and forgot to remove earlier. I think overall the amount of code is about the same between Apollo and Relay.

[gadicc]

Is anyone else working on authentication via graphQL? Is this a good place to mention it?

I'm working on an apollo-passport package, that works with PassportJS and (optionally) JSON Web Tokens (so, no need to lookup the user on every query). It's inspired by Meteor Accounts and will include a reactive UI that helps with setup too.

I have a lot of travel over the next few days but hope to have an early release out by next weekend. By then I'll have a few proposals to improve the API for packages, relating back to this thread. And setup instructions for Saturn :) (cc @tmeasday)

[siegesmund]

@gadicc I've implemented the same thing, (passport + JWT) though haven't packaged it yet. It's really pretty simple. I'd love you see your implementation.

[ciwolsey]

I wrote JWT auth without using passport. I'm interested to see what you
come up with :)

On 30 June 2016 at 17:07, Peter Siegesmund notifications@github.com wrote:

I've implemented the same thing, (passport + JWT) though haven't packaged
it yet. It's really pretty simple. I'd love you see your implementation.

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub
#28 (comment),
or mute the thread
https://github.com/notifications/unsubscribe/ABUt1KTFJ47Wi_ydRUX2wIsIveR_ceJBks5qQ-mzgaJpZM4IOOLn
.

[gadicc]

hey @siegesmund & @ciwolsey. So firstly, sorry for my super late reply... I had a lot of unexpected commitments come up, but I've been consistently working on this as time has allowed. I was about to announce an early release on the forums, but was just made aware of the apollo-accounts project too, so we're looking into combining efforts. I think we'd both value any input from you guys who have been handling similar challenges at an app level. So thanks for letting us know about that :)