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

Commit 78bf19c

Browse files
jasonkuhrtjasonkuhrt
committed
doc: simplify and clarify readme
1 parent e3c860f commit 78bf19c

File tree

2 files changed

+142
-159
lines changed

2 files changed

+142
-159
lines changed

‎README.md‎

Lines changed: 60 additions & 159 deletions
Original file line numberDiff line numberDiff line change
@@ -1,216 +1,117 @@
11
<p align="center"><img src="https://imgur.com/c6Y4tGw.png" width="150" /></p>
22

3-
# graphqlgen
3+
# graphqlgen <!-- omit in toc -->
44

55
[![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)
66

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

9-
## Features
9+
- [About](#about)
10+
- [Highlights](#highlights)
11+
- [Motivation](#motivation)
12+
- [Supported languages](#supported-languages)
13+
- [Getting started](#getting-started)
14+
- [Try out a project initializer](#try-out-a-project-initializer)
15+
- [Add to existing project](#add-to-existing-project)
16+
- [Documentation](#documentation)
17+
- [Addendum](#addendum)
18+
- [Community](#community)
19+
- [Project Status](#project-status)
20+
- [Prior Art](#prior-art)
1021

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

17-
## Documentation
24+
### Highlights
1825

19-
You can find the docs for the `graphqlgen` CLI [here](https://oss.prisma.io/graphqlgen/).
26+
- **Schema-first** Design in SDL to derive ideal types
27+
- **Type-safety** Resolvers with precise signatures including `parent`, `args` and return type
28+
- **DX** Precise resolver types puts your editor intellisense to work
29+
- **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
2030

21-
## Motivation
31+
### Motivation
2232

23-
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.
33+
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.
2434

25-
#### Supported languages:
35+
### Supported languages
2636

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

31-
## Get started
40+
Others under discussion:
3241

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

35-
Bootstrap a GraphQL server based with a ready-made `graphqlgen` setup then
36-
start the server:
44+
## Getting started
3745

38-
_With `npm`_
46+
### Try out a project initializer
3947

40-
```bash
41-
npm init graphqlgen my-app
42-
cd my-app
43-
npm start
44-
```
45-
46-
_Note: `npm init` requires npm version >= 6.2.0_
47-
48-
or
48+
1. Run initializer
4949

50-
_With `yarn`_
51-
52-
```bash
53-
yarn create graphqlgen my-app
54-
cd my-app
55-
yarn start
56-
```
50+
```bash
51+
yarn create graphqlgen my-app # npm init graphqlgen my-app
52+
cd my-app
53+
yarn start # npm run start
54+
```
5755

58-
_Note: `yarn create` requires yarn version >= 0.25_
56+
2. Edit `./my-app/src/schema.graphql` to your heart's content.
5957

60-
After updating the GraphQL schema in `./my-app/src/schema.graphql`, execute the `graphqlgen` CLI to update all resolvers:
58+
3. Generate types:
6159

62-
```
63-
graphqlgen
64-
```
60+
```
61+
yarn graphqlgen
62+
```
6563

6664
### Add to existing project
6765

68-
#### Install
69-
70-
You can install the `graphqlgen` CLI with either of the following commands:
71-
7266
```bash
73-
npm install -g graphqlgen
67+
yarn add --dev graphqlgen # npm install --save-dev graphqlgen
7468
```
7569

76-
or
70+
Then you will have access to the cli (`gg` or `graphqlgen`):
7771

7872
```bash
79-
yarn global add graphqlgen
73+
yarn -s gg --help # npm run gg --help
8074
```
8175

82-
#### Usage
83-
84-
Once installed, you can invoke the CLI as follows:
85-
8676
```
87-
graphqlgen
77+
Usage: graphqlgen or gg
78+
79+
Options:
80+
-i, --init Initialize a graphqlgen.yml file
81+
-v, --version Show version number [boolean]
82+
-h, --help Show help [boolean]
8883
```
8984

90-
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:
85+
`gg` depends on the presence of a `graphqlgen.yml` config **located in the directory where `gg` is invoked**. Here is an example:
9186

9287
```yml
9388
language: typescript
94-
9589
schema: ./src/schema.graphql
96-
context: ./src/types.ts:Context
90+
context: ./src/context.ts:Context
91+
output: ./src/generated/graphqlgen.ts
9792
models:
9893
files:
9994
- ./src/generated/prisma-client/index.ts
100-
101-
output: ./src/generated/graphqlgen.ts
102-
103-
resolver-scaffolding:
104-
output: ./src/generated/tmp-resolvers/
105-
layout: file-per-type
106-
```
107-
108-
Learn more about the configuration in the [docs](https://oss.prisma.io/graphqlgen/01-configuration.html).
109-
110-
## Support
111-
112-
- [Create a feature request](https://github.com/prisma/graphqlgen/issues/new?template=feature_request.md&labels=enhancement)
113-
- [Create a bug report](https://github.com/prisma/graphqlgen/issues/new?template=bug_report.md&labels=bug)
114-
115-
<Details><Summary><b>Note: Using <code>graphqlgen</code> in production</b></Summary>
116-
<br />
117-
118-
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.
119-
120-
</Details>
121-
122-
## Help & Community
123-
124-
[![Slack Status](https://slack.prisma.io/badge.svg)](https://slack.prisma.io)
125-
126-
Join the `#graphqlgen` channel our [Slack community](http://slack.graph.cool/) if you run into issues or have questions. We love talking to you!
127-
128-
## Benchmarks
129-
130-
Benchmarks exist for the graphqlgen package.
131-
132-
- Results can be reviewed in [history.json](https://github.com/prisma/graphqlgen/blob/master/packages/graphqlgen/benchmarks/history.json)
133-
- Run benchmarks within that package via `yarn run benchmarks`
134-
- Save results via `yarn run benchmarks --save`
135-
136-
### Folder Structure
137-
138-
```
139-
/benchmarks
140-
history.json <-- file keeping results of past benchmark runs
141-
index.ts <-- benchmark execution entrypoint
142-
/lib/* <-- base tools/types/logic for benchmark system
143-
/integration <-- integration-type benchmarks testing how quickly code-generation runs
144-
index.ts <-- integration-type benchmarks entrypoint (creates & collects benchmarks)
145-
/a <-- integration-type benchmark for a particular set of fixtures
146-
model.ts
147-
schema.graphql
148-
/b/*
149-
/c/*
15095
```
15196
152-
### Developer Guide
153-
154-
#### Adding a new integration-type benchmark
155-
156-
1. Create a new folder for your benchmark case:
157-
158-
```
159-
/benchmarks
160-
/integration
161-
/<YOUR-BENCHMARK-TITLE-HERE>
162-
```
163-
164-
2. Add fixtures containing whatever data case/pattern you're interested in benching:
165-
166-
```
167-
model.ts
168-
schema.graphql
169-
```
97+
### Documentation
17098
171-
#### Adding a new type of benchmark
99+
https://oss.prisma.io/graphqlgen
172100
173-
1. Create a new folder for your benchmark type:
174-
175-
```
176-
/benchmarks
177-
/<YOUR-BENCHMARK-TYPE-TITLE-HERE>
178-
```
101+
## Addendum
179102
180-
2. Implement an `index.ts` that exports a `collect` function:
103+
### Community
181104
182-
```
183-
/benchmarks
184-
/<YOUR-BENCHMARK-TYPE-TITLE-HERE>
185-
index.ts
186-
```
105+
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:
187106

188-
```ts
189-
import * as Benchmark from '../lib/benchmark'
107+
- [feature request](https://github.com/prisma/graphqlgen/issues/new?template=feature_request.md&labels=enhancement)
108+
- [bug report](https://github.com/prisma/graphqlgen/issues/new?template=bug_report.md&labels=bug)
190109

191-
const collect: Benchmark.Collect = () => {
192-
// TODO
193-
}
110+
### Project Status
194111

195-
export { collect }
196-
```
197-
198-
The collect function is responsible for returning benchmarks from your benchmark type to run. Some guidelines to keep in mind:
199-
200-
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.
201-
202-
2. Support all types of languages supported by graphqlgen
203-
204-
With your system in place, add benchmarks as needed, in the format your collector dictates:
205-
206-
```
207-
/benchmarks
208-
/<YOUR-BENCHMARK-TYPE-TITLE-HERE>
209-
index.ts
210-
... <-- dictated by your collector
211-
```
112+
`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).
212113

213-
## Prior Art
114+
### Prior Art
214115

215116
- [**gqlgen**](https://github.com/99designs/gqlgen) is the Golang equivalent of `graphqlgen` and served as a source of inspiration
216117
- [**graphql-code-generator**](https://github.com/dotansimha/graphql-code-generator) is a similar tool based on templates support both frontend & backend

‎packages/graphqlgen/benchmarks/README.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# Benchmarks
2+
3+
- Results can be reviewed in [history.json](https://github.com/prisma/graphqlgen/blob/master/packages/graphqlgen/benchmarks/history.json)
4+
- Run benchmarks within that package via `yarn run benchmarks`
5+
- Save results via `yarn run benchmarks --save`
6+
7+
### Folder Structure
8+
9+
```
10+
/benchmarks
11+
history.json <-- file keeping results of past benchmark runs
12+
index.ts <-- benchmark execution entrypoint
13+
/lib/* <-- base tools/types/logic for benchmark system
14+
/integration <-- integration-type benchmarks testing how quickly code-generation runs
15+
index.ts <-- integration-type benchmarks entrypoint (creates & collects benchmarks)
16+
/a <-- integration-type benchmark for a particular set of fixtures
17+
model.ts
18+
schema.graphql
19+
/b/*
20+
/c/*
21+
```
22+
23+
### Developer Guide
24+
25+
#### Adding a new integration-type benchmark
26+
27+
1. Create a new folder for your benchmark case:
28+
29+
```
30+
/benchmarks
31+
/integration
32+
/<YOUR-BENCHMARK-TITLE-HERE>
33+
```
34+
35+
2. Add fixtures containing whatever data case/pattern you're interested in benching:
36+
37+
```
38+
model.ts
39+
schema.graphql
40+
```
41+
42+
#### Adding a new type of benchmark
43+
44+
1. Create a new folder for your benchmark type:
45+
46+
```
47+
/benchmarks
48+
/<YOUR-BENCHMARK-TYPE-TITLE-HERE>
49+
```
50+
51+
2. Implement an `index.ts` that exports a `collect` function:
52+
53+
```
54+
/benchmarks
55+
/<YOUR-BENCHMARK-TYPE-TITLE-HERE>
56+
index.ts
57+
```
58+
59+
```ts
60+
import * as Benchmark from '../lib/benchmark'
61+
62+
const collect: Benchmark.Collect = () => {
63+
// TODO
64+
}
65+
66+
export { collect }
67+
```
68+
69+
The collect function is responsible for returning benchmarks from your benchmark type to run. Some guidelines to keep in mind:
70+
71+
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.
72+
73+
2. Support all types of languages supported by graphqlgen
74+
75+
With your system in place, add benchmarks as needed, in the format your collector dictates:
76+
77+
```
78+
/benchmarks
79+
/<YOUR-BENCHMARK-TYPE-TITLE-HERE>
80+
index.ts
81+
... <-- dictated by your collector
82+
```

0 commit comments

Comments
 (0)