Skip to content

Commit 1ca704d

Browse files
glennreyesglennreyes
committed
Improve README.md
1 parent ece0c2a commit 1ca704d

File tree

1 file changed

+152
-53
lines changed

1 file changed

+152
-53
lines changed

‎README.md‎

Lines changed: 152 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -1,48 +1,43 @@
1-
# [Graphpack](https://codesandbox.io/s/k3qrkl8qlv)
1+
<div align="center">
2+
<h1>Graphpack</h1>
23

34
☄️ A minimalistic zero-config GraphQL server
45

56
Check out the [demo](https://codesandbox.io/s/k3qrkl8qlv) on CodeSandbox: https://codesandbox.io/s/k3qrkl8qlv
67

7-
## What is included
8+
</div>
89

9-
Graphpack utilizes [`webpack`](https://github.com/webpack/webpack)with [`nodemon`](https://github.com/remy/nodemon) and lets you create GraphQL servers with zero configuration. It uses [`Apollo Server`](https://github.com/apollographql/apollo-server) under the hood, so we get features like [GraphQL Playground](https://github.com/prisma/graphql-playground), [GraphQL Imports](https://github.com/prisma/graphql-import) and many more right out of the box.
10+
<hr>
1011

11-
- 📦 **Zero-config** out of the box experience
12-
- 🚦 Built-in **Live reload** and automatic recompilation
12+
## What is included?
13+
14+
Graphpack utilizes [`webpack`](https://github.com/webpack/webpack) with [`nodemon`](https://github.com/remy/nodemon) and lets you create GraphQL servers with zero configuration. It uses [`Apollo Server`](https://github.com/apollographql/apollo-server) under the hood, so we get features like [GraphQL Playground](https://github.com/prisma/graphql-playground), [GraphQL Imports](https://github.com/prisma/graphql-import) and many more right out of the box.
15+
16+
- 📦 **Zero-config** out of the box
17+
- 🚦 Built-in **Live reload**
1318
- 🚨 Super-friendly error messages
14-
- 🎮 GraphQL **Playground** IDE
19+
- 🎮 **GraphQL Playground** IDE
1520
- ⭐️ **GraphQL imports** in Schema Definition Language
1621
- 🔥 [**Blazing fast**](https://twitter.com/acdlite/status/974390255393505280) bundle times
17-
- ⚡️ **ES module imports** thanks to [Babel](https://github.com/babel/babel)
18-
19-
## Install
22+
- ⚡️ **ES module imports** and dynamic `import()`'s thanks to [Babel](https://github.com/babel/babel)
2023

21-
With yarn:
24+
## Install & usage
2225

2326
```
2427
yarn add --dev graphpack
2528
```
2629

27-
With npm:
28-
29-
```
30-
npm install --save-dev graphpack
31-
```
32-
33-
## Usage
34-
35-
### Add entry files: `src/schema.graphql` & `src/resolvers.js`
30+
### Add schema and resolvers
3631

37-
Add your type definitions under `src/schema.graphql` and add some example types in [SDL](https://graphql.org/learn/schema/#type-language):
32+
Add `src/schema.graphql` and add some example types in [SDL](https://graphql.org/learn/schema/#type-language):
3833

3934
```graphql
4035
type Query {
4136
hello: String
4237
}
4338
```
4439

45-
Add your resolvers under `src/resolvers.js`:
40+
Add `src/resolvers.js`:
4641

4742
```js
4843
const resolvers = {
@@ -54,52 +49,62 @@ const resolvers = {
5449
export default resolvers;
5550
```
5651

57-
> Graphpack can resolve both `.js` and `.graphql` files. This means you can use any of these folder/file structure:
58-
>
59-
> - `src/resolvers.js`
60-
> - `src/resolvers/index.js`
61-
> - `src/schema.js`
62-
> - `src/schema/index.js`
63-
> - `src/schema.graphql`
64-
> - `src/schema/index.graphql`
65-
66-
### Setup npm run scripts
52+
### Setup `package.json` run scripts
6753

68-
Add following run scripts to your `package.json`:
54+
Add following scripts to your `package.json`:
6955

7056
```json
7157
"scripts": {
72-
"build": "graphpack build",
73-
"dev": "graphpack"
58+
"dev": "graphpack",
59+
"build": "graphpack build"
7460
},
7561
```
7662

77-
### Start dev server:
63+
### Start development server
64+
65+
To start the development server, simply run:
7866

7967
```sh
8068
yarn dev
8169
```
8270

83-
### Create a production build
71+
### Create production build
72+
73+
To create a production ready build run following command:
8474

8575
```sh
8676
yarn build
8777
```
8878

89-
### Start production build
79+
### Use production build
9080

91-
Simply run the build command and start the app
81+
Add following script that executes our build:
82+
83+
```json
84+
"scripts": {
85+
"start": "node ./build/index.js"
86+
},
87+
```
88+
89+
Following command will run the build and start the app
9290

9391
```sh
94-
yarn build
95-
node ./build/index.js
92+
yarn start
9693
```
9794

95+
> Make sure to create a build before running the start script.
96+
9897
## CLI Commands
9998

10099
### `graphpack` (alias `graphpack dev`)
101100

102-
Runs graphpack in development mode.
101+
Runs graphpack in development mode. After a successful build your output should look something like this:
102+
103+
<div align="center">
104+
<img src="https://user-images.githubusercontent.com/5080854/47042315-3e426c80-d18b-11e8-941e-e193a339e3ee.png" width="519" alt="graphpack">
105+
</div>
106+
107+
Graphpack will watch for changes in your `./src` folder and automatically reloads the server.
103108

104109
### `graphpack build`
105110

@@ -109,35 +114,129 @@ Creates a production ready build under the project roots `build` folder.
109114
110115
## Entry files
111116

112-
tbd
113-
114117
### `src/resolvers.js` (required)
115118

116-
tbd
119+
In this file you define all your resolvers:
120+
121+
```js
122+
// src/resolvers.js
123+
const resolvers = {
124+
Query: {
125+
article: (obj, args) => getArticleById(args.id),
126+
articles: () => getArticles(),
127+
},
128+
};
129+
130+
export default resolvers;
131+
```
132+
133+
> You can use any of these folder/file structure:
134+
>
135+
> - `src/resolvers.js`
136+
> - `src/resolvers/index.js`
117137
118138
### `src/schema.js` (required)
119139

120-
tbd
140+
Here you define all your GraphQL type definitions:
141+
142+
```graphql
143+
# src/schema.graphql
144+
type Article {
145+
title: String
146+
body: String
147+
}
148+
149+
type Query {
150+
article: Article
151+
articles: [Article!]!
152+
}
153+
```
154+
155+
Alternatively you can create a `src/schema.js` and use the template literal tag `gql` by [`graphql-tag`](https://github.com/apollographql/graphql-tag):
156+
157+
```js
158+
// src/schema.js
159+
import { gql } from 'graphql-tag';
160+
161+
const typeDefs = gql`
162+
type Article {
163+
title: String
164+
body: String
165+
}
166+
167+
type Query {
168+
article: Article
169+
articles: [Article!]!
170+
}
171+
`;
172+
173+
export default typeDefs;
174+
```
175+
176+
Note that you need install `graphql-tag` in this case.
177+
178+
> Graphpack can resolve both `.js` and `.graphql` files. This means you can use any of these folder/file structure:
179+
>
180+
> - `src/schema.js`
181+
> - `src/schema/index.js`
182+
> - `src/schema.graphql`
183+
> - `src/schema/index.graphql`
121184
122185
### `src/context.js`
123186

124-
tbd
187+
Create `src/context.js` and do following:
188+
189+
```js
190+
const context = req => ({
191+
/* context props here */
192+
});
193+
194+
export default context;
195+
```
196+
197+
> You can use any of these folder/file structure:
198+
>
199+
> - `src/context.js`
200+
> - `src/context/index.js`
125201
126202
### `src/config.js`
127203

128-
tbd
204+
In `src/config.js` you can set further options of your Apollo Server. Refer to the [Apollo Server docs](https://www.apollographql.com/docs/apollo-server/api/apollo-server.html#constructor-options-lt-ApolloServer-gt) for more details about the options.
205+
206+
```js
207+
// src/config.js
208+
const IS_DEV = process.env.NODE_ENV !== 'production';
209+
210+
const config = {
211+
debug: process.env.DEBUG,
212+
playground: IS_DEV,
213+
introspection: IS_DEV,
214+
mocks: IS_DEV,
215+
// ...
216+
};
129217

130-
## Customize configuration
218+
export default config;
219+
```
220+
221+
Note that you cannot to set `resolvers`, `typeDefs` or `context` in the config file. In these cases please refer to [entry files](#entry-files).
222+
223+
> You can use any of these folder/file structure:
224+
>
225+
> - `src/config.js`
226+
> - `src/config/index.js`
131227
132-
tbd
228+
## Custom configuration
133229

134-
### Webpack
230+
For custom configuration you can create a `graphpack` config file in [cosmiconfig](https://github.com/davidtheclark/cosmiconfig) format:
135231

136-
tbd
232+
- `graphpack.config.js`
233+
- `"graphpack"` field in `package.json`
234+
- `.grahpackrc` in JSON or YAML
235+
- `.graphpackrc` with the extensions `.json`, `.yaml`, `.yml`, or `.js`
137236

138-
### Apollo Server
237+
### Customize Webpack configuration
139238

140-
tbd
239+
To extend webpack, you can define a function that extends its config via `graphpack.config.js`.
141240

142241
## Acknowledgements
143242

0 commit comments

Comments
 (0)