From 50ae3490c3237d119614f9090a94b223bf56b9ca Mon Sep 17 00:00:00 2001 From: Phil Pluckthun Date: Thu, 19 Nov 2020 16:36:17 +0000 Subject: [PATCH 1/4] Update website hero text --- packages/site/src/screens/home/hero.js | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/packages/site/src/screens/home/hero.js b/packages/site/src/screens/home/hero.js index 34846e3b50..a9d3831cdc 100644 --- a/packages/site/src/screens/home/hero.js +++ b/packages/site/src/screens/home/hero.js @@ -219,8 +219,7 @@ const Hero = props => { urql - urql is a blazing-fast GraphQL client that supports React, Preact, and - Svelte (alpha). + The highly customizable and versatile GraphQL client for React, Svelte, Vue, or plain JavaScript, with which you add on features like normalized caching as you grow. From c3302962ac2cbd7dfe178beec2190e30381da66f Mon Sep 17 00:00:00 2001 From: Phil Pluckthun Date: Thu, 19 Nov 2020 16:44:10 +0000 Subject: [PATCH 2/4] Replace "Quick Start" with "Overview" as it's React-specific This isn't quite equitable for non-React users and I have high trust in the quality of our "Basics" pages. Hence "Overview" may only need a few more pointers. --- docs/README.md | 100 +++++++++++++++++++++++++++-------------------- docs/overview.md | 48 ----------------------- 2 files changed, 58 insertions(+), 90 deletions(-) delete mode 100644 docs/overview.md diff --git a/docs/README.md b/docs/README.md index 59795ef3b9..7518a54321 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,58 +1,74 @@ --- -title: Quick start -order: 0 +title: Overview +order: 1 --- -# Quick start +# Overview -`urql` is a blazingly fast, lightweight, and customisable GraphQL client. We believe in usability and adaptability, `urql` is built with extensibility at its -core, allowing you to include just the key logic for a basic app, in addition to being able to grow to support dynamic single-app applications and highly -customised infrastructure. +`urql` is an implementation of a GraphQL client, built to be both easy to use for newcomers to +GraphQL, as well as extensible, to grow to support dynamic single-app applications and highly +customized GraphQL infrastructure. In short, `urql` prioritizes usability and adaptability. -In this page we'll take a look at the quickest route to get up and running with `urql`. +As you're adopting GraphQL, `urql` becomes your primary data layer and can handle content-heavy +pages through ["Document Caching"](./basics/document-caching.md) as well as dynamic and data-heavy +apps through ["Normalized Caching"](./graphcache/normalized-caching.md). -## Installation +## Constituent Parts + +`urql` can be understood as a collection of connected parts and packages. When [getting started](./basics/getting-started.md) we only need to install a single package for our +framework of choice. We're then able to declaratively send GraphQL requests to our API. + +All framework packages — like `urql` (for React), `@urql/preact`, `@urql/svelte`, and `@urql/vue` — +wrap the [core package, `@urql/core`](./concepts/core-package.md), which we can imagine as the brain +of `urql` with most of its logic. + +As we progress with implementing `urql` into our application, we're later able to extend it by +adding ["addon packages", which we call _Exchanges_](./concepts/exchanges.md) + +## Quick Start + +We have **Getting Started** guides for +[React & +Preact](https://formidable.com/open-source/urql/docs/basics/getting-started/#react--preact), +[Svelte](https://formidable.com/open-source/urql/docs/basics/getting-started/#svelte), and +[Vue](https://formidable.com/open-source/urql/docs/basics/getting-started/#vue) which walk through +how to install the bindings for your framework of choice and set up the +[`Client`](./api/core.md#client). + +Generally for React this would look like this, where the `urql` package may be replaced with your +framework's bindings: ```sh -# npm npm i --save urql graphql -# or yarn +# or yarn add urql graphql ``` -## Making the client +The **Basics** section also features pages to [write +Queries](https://formidable.com/open-source/urql/docs/basics/queries/), +[Mutations](https://formidable.com/open-source/urql/docs/basics/mutations/), after which we could +continue learning about +[Subscriptions](https://formidable.com/open-source/urql/docs/advanced/subscriptions/). These are +among the only pages that are framework-specific. -```jsx -import { createClient, Provider } from 'urql'; +## The Documentation -const client = createClient({ url: 'https://0ufyz.sse.codesandbox.io' }); +This documentation is split into groups or sections that cover different levels of usage or areas of +interest. -const App = () => ( - - - -); -``` +- **Basics** is the section where we find the ["Getting Started" + guide](./basics/getting-started.md) and usage patterns for our framework of choice. +- **Main Concepts** then explains more about how `urql` functions, what it's made up of, and covers + the main aspects of the `Client` and GraphQL clients in general, on the ["Philosophy" + page](./concepts/philosophy.md). +- **Advanced** covers all more uncommon use-cases and contains guides that we won't need immediately + when we get started with `urql`. +- **Graphcache** documents one of the most important addons to `urql`, which adds ["Normalized + Caching" support](./graphcache/normalized-caching.md) to the `Client` and enables more complex + use-cases, smarter caching, and more dynamic apps to function. +- **Showcase** aims to list users of `urql`, third-party packages, and other helpful resources, + like tutorials and guides. +- **API** contains a detailed list of all helpers, utilities, components, and other parts of each of + `urql`'s packages, which may contain all details of each part and package. -## Querying data - -```jsx -const Todos = () => { - const [res, executeQuery] = useQuery({ - query: ` - query { todos { id text } } - `, - }); - - if (res.fetching) return

Loading...

; - if (res.error) return

Errored!

; - - return ( -
    - {res.data.todos.map(todo => ( -
  • {todo.text}
    • - ))} -
- ); -}; -``` +We hope you grow to love `urql`! diff --git a/docs/overview.md b/docs/overview.md deleted file mode 100644 index eee331737a..0000000000 --- a/docs/overview.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: Overview -order: 1 ---- - -# Overview - -`urql` is an implementation of a GraphQL client, built to be both easy to use for newcomers to -GraphQL, as well as extensible, to grow to support dynamic single-app applications and highly -customized GraphQL infrastructure. In short, `urql` prioritizes usability and adaptability. - -As you're adopting GraphQL, `urql` becomes your primary data layer and can handle content-heavy -pages through ["Document Caching"](./basics/document-caching.md) as well as dynamic and data-heavy -apps through ["Normalized Caching"](./graphcache/normalized-caching.md). - -## Constituent Parts - -`urql` can be understood as a collection of connected parts and packages. When [getting started](./basics/getting-started.md) we only need to install a single package for our -framework of choice. We're then able to declaratively send GraphQL requests to our API. - -All framework packages — like `urql`, `@urql/preact`, and `@urql/svelte` — wrap the [core -package](./concepts/core-package.md), which we can imagine as the brain of `urql` with most of its -logic. - -As we progress with implementing `urql` into our application, we're later able to extend it by -adding ["addon packages", which we call _Exchanges_](./concepts/exchanges.md) - -## The Documentation - -This documentation is split into groups or sections that cover different levels of usage or areas of -interest. - -- **Basics** is the section where we find the ["Getting Started" - guide](./basics/getting-started.md) and usage patterns for our framework of choice. -- **Main Concepts** then explains more about how `urql` functions, what it's made up of, and covers - the main aspects of the `Client` and GraphQL clients in general, on the ["Philosophy" - page](./concepts/philosophy.md). -- **Advanced** covers all more uncommon use-cases and contains guides that we won't need immediately - when we get started with `urql`. -- **Graphcache** documents one of the most important addons to `urql`, which adds ["Normalized - Caching" support](./graphcache/normalized-caching.md) to the `Client` and enables more complex - use-cases, smarter caching, and more dynamic apps to function. -- **Showcase** aims to list users of `urql`, third-party packages, and other helpful resources, - like tutorials and guides. -- **API** contains a detailed list of all helpers, utilities, components, and other parts of each of - `urql`'s packages, which may contain all details of each part and package. - -We hope you grow to love `urql`! From 33cea2a674523f175e80841e5eed4a8b463799ac Mon Sep 17 00:00:00 2001 From: Phil Pluckthun Date: Thu, 19 Nov 2020 16:45:39 +0000 Subject: [PATCH 3/4] Update first tagline in "Overview" --- docs/README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/README.md b/docs/README.md index 7518a54321..bcff8b239d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -5,7 +5,8 @@ order: 1 # Overview -`urql` is an implementation of a GraphQL client, built to be both easy to use for newcomers to +`urql` is a highly customizable and versatile GraphQL client with which you add on features like +normalized caching as you grow. It's built to be both easy to use for newcomers to GraphQL, as well as extensible, to grow to support dynamic single-app applications and highly customized GraphQL infrastructure. In short, `urql` prioritizes usability and adaptability. From 48e07bc0078e14fdae426aa2055e75956b09f2f0 Mon Sep 17 00:00:00 2001 From: Phil Pluckthun Date: Thu, 19 Nov 2020 16:47:32 +0000 Subject: [PATCH 4/4] Remove React-specific components section from urql page --- packages/site/src/screens/home/_content.js | 6 -- packages/site/src/screens/home/components.js | 59 -------------------- packages/site/src/screens/home/hero.js | 4 +- packages/site/src/screens/home/index.js | 2 - 4 files changed, 3 insertions(+), 68 deletions(-) delete mode 100644 packages/site/src/screens/home/components.js diff --git a/packages/site/src/screens/home/_content.js b/packages/site/src/screens/home/_content.js index c6dfc7d061..c106c475c1 100644 --- a/packages/site/src/screens/home/_content.js +++ b/packages/site/src/screens/home/_content.js @@ -24,12 +24,6 @@ const content = { icon: require('../../assets/clock-tile.svg'), }, ], - components: { - title: 'Minimal React Components and Hooks', - description: - "Whether you prefer a component or useQuery Hook, urql's API is intuitive to use, with full support for GraphQL Queries, Mutations and Subscriptions in both styles!", - icon: require('../../assets/react-tile.svg'), - }, preview: { description: '', media: '', diff --git a/packages/site/src/screens/home/components.js b/packages/site/src/screens/home/components.js deleted file mode 100644 index bea3e97acf..0000000000 --- a/packages/site/src/screens/home/components.js +++ /dev/null @@ -1,59 +0,0 @@ -import React from 'react'; -import PropTypes from 'prop-types'; -import styled from 'styled-components'; - -import { SecondaryTitle } from '../../components/secondary-title'; -import { BodyCopy } from '../../components/body-copy'; -import { PanelSectionWrapper } from '../../components/panel'; - -const ComponentWrapper = styled.div` - margin: 0 0 0; - display: flex; - flex-direction: column; - align-items: center; - text-align: center; - > img { - width: 100%; - max-width: 10rem; - margin-bottom: 20px; - } -`; - -const SecondaryTitleCentred = styled(SecondaryTitle)` - @media (min-width: 768px) { - text-align: center; - } -`; - -const BodyCopyCentred = styled(BodyCopy)` - margin-top: 2rem; - max-width: 28rem; - - @media (min-width: 768px) { - text-align: center; - } - - @media (min-width: 1024px) { - max-width: 20vw; - } -`; - -const Components = props => { - return ( - - - - {props.components.title} - {props.components.description} - - - ); -}; - -Components.displayName = 'Components'; - -Components.propTypes = { - components: PropTypes.object, -}; - -export default Components; diff --git a/packages/site/src/screens/home/hero.js b/packages/site/src/screens/home/hero.js index a9d3831cdc..932c76aa3a 100644 --- a/packages/site/src/screens/home/hero.js +++ b/packages/site/src/screens/home/hero.js @@ -219,7 +219,9 @@ const Hero = props => { urql - The highly customizable and versatile GraphQL client for React, Svelte, Vue, or plain JavaScript, with which you add on features like normalized caching as you grow. + The highly customizable and versatile GraphQL client for React, + Svelte, Vue, or plain JavaScript, with which you add on features like + normalized caching as you grow. diff --git a/packages/site/src/screens/home/index.js b/packages/site/src/screens/home/index.js index 4bd0de6d01..d432d44afd 100644 --- a/packages/site/src/screens/home/index.js +++ b/packages/site/src/screens/home/index.js @@ -4,7 +4,6 @@ import { usePrefetch } from 'react-static'; import { useMarkdownTree } from 'react-static-plugin-md-pages'; import Features from './features'; -import Components from './components'; import GetStarted from './get-started'; import MoreOSS from './more-oss'; import content from './_content'; @@ -23,7 +22,6 @@ const Home = () => {
-