1.0 status and documentation

[hanno-jonlay]

Hey @KyleAMathews

I've been following Gatsby for a while as a potential replacement for a static website template setup we've built that's based on Middleman. I'm keen to move away from Ruby as a build tool and get onto JS, since we don't use Ruby anywhere else (and it's slooooooowwwww).

1.0 looks super exciting! Especially the new GraphQL layer - that seems like it might be the thing which finally makes it possible to easily pull in an external data source, like we do right now with Middleman's dynamic proxies.

The biggest barrier I've had to really digging in to the 1.0 alphas is:

1. It's not immediately clear how usable some of the new alpha functionality is, and how to get it working.
2. It's tricky to estimate the rough timeline when 1.0 might be documented and usable for more than hobby projects. Weeks, months, years?

I know you already have a task for the marketing/docs site: #149

Hope it's not too cheeky to suggest that:

• You allow 1.0 docs to build themselves on Netlify already and put a URL to these inside your master branch README. Even if the design is terrible, just having alpha docs on a public URL would be really helpful.
• You maybe put some of the scrappy first versions of docs for stuff like the GraphQL work so that it's on a docs page, rather than buried in an issue here? That should hopefully make it easier for others to iterate on the docs later on, too.

I'd love to explore 1.0 deeper, so while I know it's a massive task to manage all of the work you've got going on right now, I just wanted to mention these things. They'd definitely make a big difference to how easy it is for people to understand and explore 1.0!

Either way, can't wait till things are eventually launch ready--good luck! 😄

[KyleAMathews]

Hey! Docs & website for 1.0 are definitely a priority and coming soon. Part of the problem w/ getting out docs is I've been really busy on a project for a client who's been paying for much of the development of 1.0 stuff so far :-) But the alphas are definitely getting more polished — we're about to launch something in the coming weeks.

A 1.0 release is on the order of months. Remaining work to do roughly is write plugin system, figure out core data structures, testing, build a solid system for GraphQL + files, write docs + build the website, build out core plugins, create example websites.

But long before all that's done, you should be able to start building on top of the 1.0 stuff provided you have some tolerance for breaking changes and missing documentation :-) Like I mentioned, I have several projects for clients I'm building on the 1.0 stuff and things are working really well.

On digging into 1.0 more — have you seen the "how you can test" section for the 1.0 roadmap? #419 There are several sites you can play with.

The GraphQL layer hasn't gotten as much work yet but that's changing soon. Speaking actually on Gatsby @ the GraphQL Summit this week and am working on some demos. Will be building way for you to extend the GraphQL schema yourself very soon.

@stefanoverna from DatoCMS has been doing some very interesting explorations in this area. Check out his tweet https://twitter.com/datocms/status/787223422728372225

Also the code for the example site he's built https://github.com/datocms/gatsby-example/blob/master/gatsby-node.js

He forked Gatsby slightly (won't be necessary soon) gatsbyjs:v1.0.0-alpha.10...datocms:datocms-integration

And here's the DatoCMS Gatsby plugin https://github.com/datocms/gatsby-datocms-source

Would love your help exploring this stuff! There's a lot of interesting possibilities here but I'm not really sure yet on the best patterns etc. so the more explorations and prototypes the better! If you wanted to build a sample site or two integrating with a 3rd party API that'd be super helpful.

[stefanoverna]

eager to listen your feedbacks guys :)

[KyleAMathews]

Just added an API for adding your own types, modifyGraphQLFields. This may or may not survive #520 but it'll give everyone a way to start playing around with the GraphQL stuff sooner than later. Thanks for the kickstart @jonlay :-)

To use it, install the latest alpha, alpha6, and in your gatsby-node.js add some code like:

exports.modifyGraphQLFields = ({ types }) => {
  types.test = {
    type: new GraphQLObjectType({
      name: 'test',
      description: 'just testing',
      fields: () => ({
        hello: {
          type: GraphQLString,
        },
      }),
    }),
    resolve (root, args) {
      return { hello: 'world' }
    },
  }

  return types
}

If you're doing async work to setup your type(s), you can return a promise.

[Ognian]

I'm on alpha 10;
In the frontmatter of my .md file I have added an object:

embedMap:
  lat: 48.2
  lng: 16.3
  zoom: 16
  popupText1: xxxxxx  
  popupText2: yyyyyy
  popupText3: zzzz
  popupText4: aaaa

since objects are not inferred I have to define the type

tried by inserting in gatsby-node.js:

import {GraphQLObjectType, GraphQLFloat, GraphQLInt, GraphQLString} from "graphql"

exports.modifyGraphQLFields = ({ types }) => {
    types.embedMap = {
        type: new GraphQLObjectType({
            name: 'embedMap',
            description: 'add a map',
            fields: () => ({
                lat: {
                    type: GraphQLFloat,
                },
                lng: {
                    type: GraphQLFloat,
                },
                zoom: {
                    type: GraphQLInt,
                },
                popupText1: {
                    type: GraphQLString,
                },
                popupText2: {
                    type: GraphQLString,
                },
                popupText3: {
                    type: GraphQLString,
                },
                popupText4: {
                    type: GraphQLString,
                },

            }),
        }),
        resolve (root, args) {
            return { ...args }
        },
    }

    return types
}

BUT got the following error

UNHANDLED REJECTION Error: Frontmatter.embedMap field type must be Output Type but got: function GraphQLObjectType(config) {
    _classCallCheck(this, GraphQLObjectType);

    (0, _invariant2.default)(config.name, 'Type must be named.');
    (0, _assertValidName.assertValidName)(config.name);
    this.name = config.name;
    this.description = config.description;
    if (config.isTypeOf) {
      (0, _invariant2.default)(typeof config.isTypeOf === 'function', this.name + ' must provide "isTypeOf" as a function.');
    }
    this.isTypeOf = config.isTypeOf;
    this._typeConfig = config;
  }.
  at invariant (/storage/safe/ogi-it/Projekte/EviOrdi/EviWeb2/node_modules/graphql/jsutils/invariant.js:19:11)
  at /storage/safe/ogi-it/Projekte/EviOrdi/EviWeb2/node_modules/graphql/type/definition.js:280:29
...

Somehow I'm stuck now, looks like that this definition is wrong but...
Can someone point me in the right direction?
Thanks
Ognian

[KyleAMathews]

@Ognian you need to modify the markdown -> frontmatter -> embedMap field to your hand-crafted one. Which I'm not 100% sure graphql-js lets you do but I think it does.

This will be getting much better soon! Been working last couple weeks full time on new GraphQL layer. Starting to get nice :-)

[Ognian]

OK, thank you, I tried if this can be done easily but did not succeed. For now I will try other things an wait for the next awesome version :-)

[hanno-jonlay]

Hey @KyleAMathews just wanted to apologise for not replying earlier to your great message and send a quick one before I disappear on holiday! Work and personal life got a bit crazy.

I was tinkering with Gatsby as a personal project for a little while, but my teammate @marcelkalveram has actually started to try it out on a proper work project (admittedly only the pre-1.0) while we validate the stack a bit more.

I was worried about how easy Gatsby would be for designers who are less comfortable working with pure JS stuff. But I think that the positives outweigh the negatives of dev complexity and we're going to give 1.0 a proper try sometime from January and see where we can go with it. I'm quite interested to explore integrating it with the WordPress Rest API so that it's really easily for editors to manage our blog.

I did actually get a chance to try @stefanoverna's DatoCMS product in the meantime when some other projects demanded it, and I'm super impressed with that. So that's gonna be very cool to be able to easily integrate with Gatsby so at least we can keep a few more people out of those templates 😉

So definitely following closely and hopeful to have more of a chance to give useful feedback soon.

[KyleAMathews]

@jonlay no worries! Open source is extreme async communication/collaboration by design!

And exciting! My latest 1.0 prototyping is starting to come together https://twitter.com/kylemathews/status/807319166449434624

Have some client work to build on it then will be releasing another alpha.

Looking forward to playing with DatoCMS as well 😄

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[stale]

This issue has been automatically closed due to inactivity.