Skip to content
This repository has been archived by the owner on Dec 8, 2021. It is now read-only.

Commit

Permalink
doc: simplify and clarify readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@jasonkuhrt
jasonkuhrt committed Feb 5, 2019
1 parent e3c860f commit 78bf19c
Show file tree
Hide file tree
Showing 2 changed files with 142 additions and 159 deletions.
219 changes: 60 additions & 159 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,216 +1,117 @@
<p align="center"><img src="https://imgur.com/c6Y4tGw.png" width="150" /></p>

# graphqlgen
# graphqlgen <!-- omit in toc -->

[![CircleCI](https://circleci.com/gh/prisma/graphqlgen.svg?style=shield)](https://circleci.com/gh/prisma/graphqlgen) [![npm version](https://badge.fury.io/js/graphqlgen.svg)](https://badge.fury.io/js/graphqlgen)

> Generate & scaffold type-safe resolvers based on your GraphQL Schema in TypeScript, Flow & Reason
Generate & scaffold type-safe resolvers based on your GraphQL Schema in TypeScript, Flow & Reason

## Features
- [About](#about)
- [Highlights](#highlights)
- [Motivation](#motivation)
- [Supported languages](#supported-languages)
- [Getting started](#getting-started)
- [Try out a project initializer](#try-out-a-project-initializer)
- [Add to existing project](#add-to-existing-project)
- [Documentation](#documentation)
- [Addendum](#addendum)
- [Community](#community)
- [Project Status](#project-status)
- [Prior Art](#prior-art)

- **🚀 Schema-first:** Based on your GraphQL schema (SDL) & model definitions
- **🤝 Type-safe:** Strong mapping between your GraphQL schema and resolvers, input arguments and models
- **♻️ Codegen & scaffolding workflows:** Minimal resolver boilerplate & automatically generated type definitions
- **😍 Awesome DX:** Auto-completion & Intellisense in VSCode, Webstorm, Atom, VIM & other editors
- **💅 Ecosystem compatibility:** Supports [prettier](https://github.com/prettier/prettier) and [graphql-import](https://github.com/prisma/graphql-import) out of the box
## About

## Documentation
### Highlights

You can find the docs for the `graphqlgen` CLI [here](https://oss.prisma.io/graphqlgen/).
- **Schema-first** Design in SDL to derive ideal types
- **Type-safety** Resolvers with precise signatures including `parent`, `args` and return type
- **DX** Precise resolver types puts your editor intellisense to work
- **Ecosystem Interop** codegen suitable for Yoga 1 or Apollo Server and supports [prettier](https://github.com/prettier/prettier) and [graphql-import](https://github.com/prisma/graphql-import) out of the box

## Motivation
### Motivation

Programming in type-safe environments provides a lot of benefits and gives you confidence about your code. `graphqlgen` leverages the strongly typed GraphQL schema with the goal of making your backend type-safe while reducing the need to write boilerplate through code generation.
Programming in type-safe environments can contribute toward great confidence in your code's integrity. `graphqlgen` aims to leverage the GraphQL type system to make your resolvers completely type-safe. This is important because resolvers are the heart of any graphql service and yet the hardest to statically type due to their dynaminism.

#### Supported languages:
### Supported languages

- `TypeScript`
- `Flow`
- `Reason` ([coming soon](https://github.com/prisma/graphqlgen/issues/253))

## Get started
Others under discussion:

### Start from scratch
- [`reason`](https://github.com/prisma/graphqlgen/issues/253)

Bootstrap a GraphQL server based with a ready-made `graphqlgen` setup then
start the server:
## Getting started

_With `npm`_
### Try out a project initializer

```bash
npm init graphqlgen my-app
cd my-app
npm start
```

_Note: `npm init` requires npm version >= 6.2.0_

or
1. Run initializer

_With `yarn`_

```bash
yarn create graphqlgen my-app
cd my-app
yarn start
```
```bash
yarn create graphqlgen my-app # npm init graphqlgen my-app
cd my-app
yarn start # npm run start
```

_Note: `yarn create` requires yarn version >= 0.25_
2. Edit `./my-app/src/schema.graphql` to your heart's content.
After updating the GraphQL schema in `./my-app/src/schema.graphql`, execute the `graphqlgen` CLI to update all resolvers:
3. Generate types:
```
graphqlgen
```
```
yarn graphqlgen
```
### Add to existing project
#### Install

You can install the `graphqlgen` CLI with either of the following commands:

```bash
npm install -g graphqlgen
yarn add --dev graphqlgen # npm install --save-dev graphqlgen
```
or
Then you will have access to the cli (`gg` or `graphqlgen`):
```bash
yarn global add graphqlgen
yarn -s gg --help # npm run gg --help
```
#### Usage

Once installed, you can invoke the CLI as follows:

```
graphqlgen
Usage: graphqlgen or gg
Options:
-i, --init Initialize a graphqlgen.yml file
-v, --version Show version number [boolean]
-h, --help Show help [boolean]
```
The invocation of the command depends on a configuration file called `graphqlgen.yml` which **must be located in the directory where `graphqlgen` is invoked**. Here is an example:
`gg` depends on the presence of a `graphqlgen.yml` config **located in the directory where `gg` is invoked**. Here is an example:
```yml
language: typescript

schema: ./src/schema.graphql
context: ./src/types.ts:Context
context: ./src/context.ts:Context
output: ./src/generated/graphqlgen.ts
models:
files:
- ./src/generated/prisma-client/index.ts

output: ./src/generated/graphqlgen.ts

resolver-scaffolding:
output: ./src/generated/tmp-resolvers/
layout: file-per-type
```
Learn more about the configuration in the [docs](https://oss.prisma.io/graphqlgen/01-configuration.html).
## Support
- [Create a feature request](https://github.com/prisma/graphqlgen/issues/new?template=feature_request.md&labels=enhancement)
- [Create a bug report](https://github.com/prisma/graphqlgen/issues/new?template=bug_report.md&labels=bug)
<Details><Summary><b>Note: Using <code>graphqlgen</code> in production</b></Summary>
<br />
While `graphqlgen` is ready to be used in production, it's still in active development and there might be breaking changes before it hits 1.0. Most changes will just affect the configuration and generated code layout but not the behaviour of the code itself.

</Details>

## Help & Community

[![Slack Status](https://slack.prisma.io/badge.svg)](https://slack.prisma.io)

Join the `#graphqlgen` channel our [Slack community](http://slack.graph.cool/) if you run into issues or have questions. We love talking to you!

## Benchmarks

Benchmarks exist for the graphqlgen package.

- Results can be reviewed in [history.json](https://github.com/prisma/graphqlgen/blob/master/packages/graphqlgen/benchmarks/history.json)
- Run benchmarks within that package via `yarn run benchmarks`
- Save results via `yarn run benchmarks --save`

### Folder Structure

```
/benchmarks
history.json <-- file keeping results of past benchmark runs
index.ts <-- benchmark execution entrypoint
/lib/* <-- base tools/types/logic for benchmark system
/integration <-- integration-type benchmarks testing how quickly code-generation runs
index.ts <-- integration-type benchmarks entrypoint (creates & collects benchmarks)
/a <-- integration-type benchmark for a particular set of fixtures
model.ts
schema.graphql
/b/*
/c/*
```
### Developer Guide
#### Adding a new integration-type benchmark
1. Create a new folder for your benchmark case:
```
/benchmarks
/integration
/<YOUR-BENCHMARK-TITLE-HERE>
```
2. Add fixtures containing whatever data case/pattern you're interested in benching:
```
model.ts
schema.graphql
```
### Documentation
#### Adding a new type of benchmark
https://oss.prisma.io/graphqlgen
1. Create a new folder for your benchmark type:
```
/benchmarks
/<YOUR-BENCHMARK-TYPE-TITLE-HERE>
```
## Addendum
2. Implement an `index.ts` that exports a `collect` function:
### Community
```
/benchmarks
/<YOUR-BENCHMARK-TYPE-TITLE-HERE>
index.ts
```
Join us at `#graphqlgen` in our [Slack group](https://slack.prisma.io) and if you have more fleshed out ideas, bug reports etc. create a Github issue:
```ts
import * as Benchmark from '../lib/benchmark'
- [feature request](https://github.com/prisma/graphqlgen/issues/new?template=feature_request.md&labels=enhancement)
- [bug report](https://github.com/prisma/graphqlgen/issues/new?template=bug_report.md&labels=bug)
const collect: Benchmark.Collect = () => {
// TODO
}
### Project Status
export { collect }
```

The collect function is responsible for returning benchmarks from your benchmark type to run. Some guidelines to keep in mind:

1. Adding new benchmarks to this type should be trivial, therefore, should only require the addition of fixtures and/or benchmark-specific code. For example the benchmark type should be prepared to pick up new folders automatically.

2. Support all types of languages supported by graphqlgen

With your system in place, add benchmarks as needed, in the format your collector dictates:

```
/benchmarks
/<YOUR-BENCHMARK-TYPE-TITLE-HERE>
index.ts
... <-- dictated by your collector
```
`graphqlgen` is still in early stage development where breaking changes and tool design are a fluid matter. Feedback is deeply appreciated. You may feel comfortable giving it a try on production systems since there is no runtime aspect and hence quite safe to do so (save for a few optional default resolvers).
## Prior Art
### Prior Art
- [**gqlgen**](https://github.com/99designs/gqlgen) is the Golang equivalent of `graphqlgen` and served as a source of inspiration
- [**graphql-code-generator**](https://github.com/dotansimha/graphql-code-generator) is a similar tool based on templates support both frontend & backend
Expand Down
82 changes: 82 additions & 0 deletions packages/graphqlgen/benchmarks/README.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
# Benchmarks

- Results can be reviewed in [history.json](https://github.com/prisma/graphqlgen/blob/master/packages/graphqlgen/benchmarks/history.json)
- Run benchmarks within that package via `yarn run benchmarks`
- Save results via `yarn run benchmarks --save`

### Folder Structure

```
/benchmarks
history.json <-- file keeping results of past benchmark runs
index.ts <-- benchmark execution entrypoint
/lib/* <-- base tools/types/logic for benchmark system
/integration <-- integration-type benchmarks testing how quickly code-generation runs
index.ts <-- integration-type benchmarks entrypoint (creates & collects benchmarks)
/a <-- integration-type benchmark for a particular set of fixtures
model.ts
schema.graphql
/b/*
/c/*
```

### Developer Guide

#### Adding a new integration-type benchmark

1. Create a new folder for your benchmark case:

```
/benchmarks
/integration
/<YOUR-BENCHMARK-TITLE-HERE>
```

2. Add fixtures containing whatever data case/pattern you're interested in benching:

```
model.ts
schema.graphql
```

#### Adding a new type of benchmark

1. Create a new folder for your benchmark type:

```
/benchmarks
/<YOUR-BENCHMARK-TYPE-TITLE-HERE>
```

2. Implement an `index.ts` that exports a `collect` function:

```
/benchmarks
/<YOUR-BENCHMARK-TYPE-TITLE-HERE>
index.ts
```

```ts
import * as Benchmark from '../lib/benchmark'

const collect: Benchmark.Collect = () => {
// TODO
}

export { collect }
```

The collect function is responsible for returning benchmarks from your benchmark type to run. Some guidelines to keep in mind:

1. Adding new benchmarks to this type should be trivial, therefore, should only require the addition of fixtures and/or benchmark-specific code. For example the benchmark type should be prepared to pick up new folders automatically.

2. Support all types of languages supported by graphqlgen

With your system in place, add benchmarks as needed, in the format your collector dictates:

```
/benchmarks
/<YOUR-BENCHMARK-TYPE-TITLE-HERE>
index.ts
... <-- dictated by your collector
```

0 comments on commit 78bf19c

Please sign in to comment.