grand-stack/grandstack.io

GRANDstack website

grandstack.io's Issues

GRANDstack Starter page hard to follow

hard-to-follow

https://grandstack.io/docs/getting-started-grand-stack-starter#usage

Document CLI tooling

• grandstack CLI
• create-grandstack-app

Change index page title

from GRANDstack | GRANDstack

to site.title + description

"GRANDstack | Build fullstack GraphQL applications with ease"

Document cypher template tag

Possibly in the "Custom logic" guide?

Covert all @cypher directive examples to use it?

GraphQL syntax highlighting doesn't handle multi-line string argument for directives

Multi-line string arguments are frequently used with the @cypher directive, however the Prism syntax highlighter doesn't recognize these strings as multi-line strings and syntax highlights them as GraphQL.

For example:

type Business {
    businessId: ID!
    averageStars: Float! @cypher(statement:"MATCH (this)<-[:REVIEWS]-(r:Review) RETURN avg(r.stars)")
    recommended(first: Int = 1): [Business] @cypher(statement: """
      MATCH (this)<-[:REVIEWS]-(:Review)<-[:WROTE]-(:User)-[:WROTE]->(:Review)-[:REVIEWS]->(rec:Business)
      WITH rec, COUNT(*) AS score
      RETURN rec ORDER BY score DESC LIMIT $first
    """)
    name: String!
    city: String!
    state: String!
    address: String!
    location: Point!
    reviews: [Review] @relation(name: "REVIEWS", direction: "IN")
    categories: [Category] @relation(name: "IN_CATEGORY", direction: "OUT")
}

Include example of using input type as argument for cypher directive field

See neo4j-graphql/neo4j-graphql-js#434

Add language indicator to each code snippet

There is a mix of Cypher, javascript, graphql typedefs vs queries, java, shell commands, etc

Add an indicator to each snippet so the reader can see clearly what language the code snippet is referencing.

Perhaps use the tabbed navigation (with a single tab) as a precursor to when we have multiple language examples (javascript and java, etc)

Add "Querying With GraphQL" page

Use one of the example GraphQL schemas (either movies or business reviews) and show the features of the generated GraphQL API with GraphQL query examples (and GraphiQL).

Also show the generated Cypher queries in a tab.

Demonstrate:

• Query field per type
• Generated query field arguments
• Ordering
• Selection set
• Nested selections
• Nested field arguments
• Filtering (basic)
• Cypher directive fields

Who is the audience for this page? (new to GraphQL? new to Neo4j?)

How does this impact other pages with similar content?

Embed GraphiQL examples

Since docs files are now MDX, React components and JSX can easily be embedded. Embed GraphiQL examples showing features using the movies.grandstack.io schema for relevant pages

Add tutorial

Move cypher directive content to its own page

The cypher directive feature is powerful enough that it should have its own page, with examples showing:

• computed scalar fields
• computed object and array fields
• custom top level query fields
• custom top level mutation fields
• use cases for the above
• using cypher / GraphQL field parameters
• using context values

Additionally, consider adding a guide to show best practice usage of above (and what not to do)

Document GraphQL on Neo4j Sandbox

Perhaps in getting started section?

Include embedded codesandbox example

Perhaps on the main landing page

Add "How to use this site" page

Explain difference between docs pages and guide pages.
Use 2 consistent GraphQL schemas (movies and businesses) throughout. Link to code for the GraphQL APIs and link to Codesandbox examples for them (using neo4j demo databases)

Add more blogs / videos to Resources page

I added content from blog.grandstack.io and some YouTube videos but I’m sure I missed some. Dev.to for example? Some of Ian’s and Michael P.’s posts?

Improve documentation for relationship type mutations

Page: https://grandstack.io/docs/graphql-relationship-types

missing

there is very poor documentation on how to write mutations with relationships.

Update get started "GRAND" Diagram

Will try to put some time aside and attempt to create a more decent diagram, but if someone else can do that meanwhile, please do so.

This is diagram takes me 20 years back.
Nothing wrong with its contents, but its way to ugly to look at 🙈 sorry.

Document Docker image

Document update mutation behavior for temporal and spatial types

Make it clear that update and merge mutations replace the value of the temporal and spatial properties, which means all components of a DateTime (for example) must be provided, not just the components intended to be updated.

Add page for implementing custom resolvers

Add syntax highlighter for Cypher

Docusaurus v2 uses Prism which does not have a Cypher mode. Figure out how to add a custom language mode and add locally, or contribute back to Prism

Rework neo4j-graphql.js User Guide page

This page

grandstack.io/docs/neo4j-graphql-js.html

has a sub-optimal example and flow (usage of neo4jgraphql function, outdated apollo server and neo4j driver example)

Update the example to be more prescriptive of the optimal way to use neo4j-graphql.js and rework the flow of the page.

Include blog highlights

Include preview of content from the blog on landing page

Implementing multiple interfaces

How is the case of implementing multiple interfaces handled?

Or interfaces that implement other interfaces?

Fixes for mobile

The landing page has some weird margin on the right on mobile.

Also video embeds seems to be fixed width, which are too wide for mobile

Add page listing all directives (with examples)

Document using multiple databases with inferSchema

missing

Missing documentation for how to use multiple database with inferSchema

https://grandstack.io/docs/infer-graphql-schema-database/#how-to-use-inferschema

inferSchema is missing documentation for how to use with non-default database

inferSchema(driver, {database: "foobar").then( result => {
  console.log(result.typeDefs);
}

Document list filters

The feature added here neo4j-graphql/neo4j-graphql-js#513 is not evident from the docs, and the exact behaviour for some is unintuitive even after reading the tests