docs

.eslintrc.js

@@ -69,6 +69,22 @@ module.exports = {
         '@typescript-eslint/strict-boolean-expressions': 'off',
         '@typescript-eslint/explicit-module-boundary-types': 'off'
       }
+    },
+    {
+      files: [
+        'docs/src/**/*.{ts,tsx}'
+      ],
+      env: {
+        jest: true
+      },
+      rules: {
+        '@typescript-eslint/explicit-function-return-type': 'off',
+        '@typescript-eslint/explicit-module-boundary-types': 'off',
+        '@typescript-eslint/no-floating-promises': 'off',
+        '@typescript-eslint/no-var-requires': 'off',
+        '@typescript-eslint/require-await': 'off',
+        '@typescript-eslint/strict-boolean-expressions': 'off'
+      }
     }
   ],
   rules: {

.github/workflows/gh-pages.yml

@@ -0,0 +1,56 @@
+name: Deploy Docusaurus with GitHub Pages
+
+on:
+  push:
+    branches: ["docs"]
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: docs
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '20'
+
+      - name: Install dependencies
+        run: |
+          cd docs
+          yarn install
+
+      - name: Build Docusaurus site
+        run: |
+          cd docs
+          yarn build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/build
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

docs/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

docs/README.md

@@ -0,0 +1,41 @@
+# Website
+
+This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```
+$ yarn
+```
+
+### Local Development
+
+```
+$ yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```
+$ yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+### Deployment
+
+Using SSH:
+
+```
+$ USE_SSH=true yarn deploy
+```
+
+Not using SSH:
+
+```
+$ GIT_USER=<Your GitHub username> yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

docs/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

docs/docs/angular/advanced/_category_.json

@@ -0,0 +1,6 @@
+{
+  "position": 7,
+  "label": "Advanced",
+  "collapsible": true,
+  "collapsed": false
+}

docs/docs/angular/advanced/custom-client.mdx

@@ -0,0 +1,35 @@
+---
+sidebar_position: 4
+---
+
+import Link from '@docusaurus/Link';
+import TabItem from '@theme/TabItem';
+import Tabs from '@theme/Tabs';
+
+# Custom ApolloClient
+
+## Overview
+By default, **Apollo Orbit** uses the default `ApolloClient` implementation provided by `@apollo/client/core` library.  
+But, it is possible in some scenarios that an application needs to provide its own custom implementation of `ApolloClient`.
+
+This can be achieved by providing a custom `ApolloClientFactory` function to `APOLLO_CLIENT_FACTORY` injection token.
+
+## Usage
+```typescript
+// code-add-line
+import { ApolloClientFactory } from '@apollo-orbit/angular';
+import { CustomApolloClient } from 'custom-apollo-client';
+
+const customApolloClientFactory: ApolloClientFactory = (options: ApolloClientOptions<NormalizedCacheObject>): ApolloClient<NormalizedCacheObject> => {
+  return new CustomApolloClient(options);
+};
+
+...
+
+{
+  providers: [
+    // code-add-line
+    { provide: APOLLO_CLIENT_FACTORY, useValue: customApolloClientFactory }
+  ]
+}
+```

docs/docs/angular/advanced/entry-point.mdx

@@ -0,0 +1,66 @@
+---
+sidebar_position: 5
+---
+
+import Link from '@docusaurus/Link';
+import TabItem from '@theme/TabItem';
+import Tabs from '@theme/Tabs';
+
+# Library Entry Point
+
+## Overview
+An entry point is the path used to import a library into your application.
+
+**Apollo Orbit** provides two entry points into the library:
+
+1. `@apollo-orbit/angular/core`: This is a full-featured **Angular** implementation of `@apollo/client` library.
+2. `@apollo-orbit/angular`: Provides the full functionality of `@apollo-orbit/angular/core` **+** all the state management capabilities covered in [State section](../../state/intro/)
+
+If, for some reason, you're only interested in the core functionality of **Apollo Orbit** without the added state management capabilities, you can follow the steps below:
+
+### Using `@apollo-orbit/angular/core`
+
+#### Update ESLint
+Add the following rule to *.eslintrc.js* to ensure the correct import path is used in your application.
+```javascript title=".eslintrc.js "
+'no-restricted-imports': [
+    'error',
+    {
+        paths: [
+            {
+              name: '@apollo/client',
+              message: 'Please use @apollo/client/core instead.'
+            },
+            // code-add-start
+            {
+              name: '@apollo-orbit/angular',
+              message: 'Please use @apollo-orbit/angular/core instead.'
+            }
+            // code-add-end
+        ]
+    }
+]
+```
+
+#### Update codegen.ts
+Add `importFromCore` config to *codegen.ts* file created in the [environment setup guide](../../get-started/setup-environment/#create-codegents).
+
+```typescript title="codegen.ts"
+import { CodegenConfig } from '@graphql-codegen/cli';
+
+const config: CodegenConfig = {
+  schema: [
+    ...
+  ],
+  config: {
+    // code-add-line
+    importFromCore: true,
+    ...
+  },
+  generates: {
+    ...
+  }
+};
+
+export default config;
+```

docs/docs/angular/advanced/link.mdx

@@ -0,0 +1,138 @@
+---
+sidebar_position: 1
+---
+
+import Link from '@docusaurus/Link';
+import TabItem from '@theme/TabItem';
+import Tabs from '@theme/Tabs';
+
+# Apollo Link
+
+## Overview
+**Apollo Orbit** is compatible with all built-in <Link to="https://www.apollographql.com/docs/react/api/link/introduction">Apollo Link</Link>s, with the exception of `HTTP` and `HTTP Batch` links. For these, **Apollo Orbit** provides its own implementation that leverages **Angular**'s `HttpClient`. This allows for the use of **Angular**'s built-in features such as `HttpInterceptor`s, `TransferState`, etc...
+
+## HTTP Link
+`HttpLink` is a terminating link that sends a GraphQL operation to a remote endpoint over HTTP.
+
+It is registered using `withHttpLink` feature, which provides a `HttpLinkFactory` function that can be used to create an instance of `HttpLink`.
+
+### Usage
+```typescript
+import { NgModule, inject } from '@angular/core';
+import { InMemoryCache, provideApolloOrbit, withApolloOptions } from '@apollo-orbit/angular';
+// code-add-line
+import { HttpLinkFactory, withHttpLink } from '@apollo-orbit/angular/http';
+
+...
+
+{ 
+  providers: [
+    provideApolloOrbit(
+      withApolloOptions(() => {
+        // code-add-start
+        const httpLinkFactory = inject(HttpLinkFactory);
+        const httpLink = httpLinkFactory.create({ uri: 'http://localhost:4000/graphql' });
+        // code-add-end
+
+        return {
+          cache: new InMemoryCache(),
+          // code-add-line
+          link: httpLink
+        };
+      }),
+      // code-add-line
+      withHttpLink()
+    )
+  ]
+}
+```
+
+
+## HTTP Batch Link
+`BatchHttpLink` is a terminating link that batches an array of individual GraphQL operations into a single HTTP request that's sent to a single GraphQL endpoint.
+
+It is registered using `withHttpLink` feature, which provides a `BatchHttpLinkFactory` function that can be used to create an instance of `BatchHttpLink`.
+
+### Usage
+```typescript
+import { NgModule, inject } from '@angular/core';
+import { InMemoryCache, provideApolloOrbit, withApolloOptions } from '@apollo-orbit/angular';
+// code-add-line
+import { BatchHttpLinkFactory, withBatchHttpLink } from '@apollo-orbit/angular/batch-http';
+
+...
+
+{ 
+  providers: [
+    provideApolloOrbit(
+      withApolloOptions(() => {
+        // code-add-start
+        const batchHttpLinkFactory = inject(BatchHttpLinkFactory);
+        const batchHttpLink = batchHttpLinkFactory.create({ uri: 'http://localhost:4000/graphql' });
+        // code-add-end
+
+        return {
+          cache: new InMemoryCache(),
+          // code-add-line
+          link: batchHttpLink
+        };
+      }),
+      // code-add-line
+      withBatchHttpLink()
+    )
+  ]
+}
+```
+
+## Automatic Persisted Queries Link (APQ)
+This link does not require a specific **Angular** implementation and works as-is with **Apollo Orbit**.
+
+### Install dependencies
+
+<Tabs>
+  <TabItem value="yarn" label="yarn" default>
+
+    ```bash
+    yarn add --dev crypto-hash
+    ```
+
+  </TabItem>
+  <TabItem value="npm" label="npm">
+
+    ```bash
+    npm install --save-dev crypto-hash
+    ```
+
+  </TabItem>
+</Tabs>
+
+### Usage
+```typescript
+import { NgModule, inject } from '@angular/core';
+import { InMemoryCache, provideApolloOrbit, withApolloOptions } from '@apollo-orbit/angular';
+import { HttpLinkFactory, withHttpLink } from '@apollo-orbit/angular/http';
+// code-add-start
+import { createPersistedQueryLink } from '@apollo/client/link/persisted-queries';
+import { sha256 } from 'crypto-hash';
+// code-add-end
+
+...
+
+{ 
+  providers: [
+    provideApolloOrbit(
+      withApolloOptions(() => {
+        const httpLinkFactory = inject(HttpLinkFactory);
+        const httpLink = httpLinkFactory.create({ uri: 'http://localhost:4000/graphql' });
+
+        return {
+          cache: new InMemoryCache(),
+          // code-add-line
+          link: createPersistedQueryLink({ sha256 }).concat(httpLink)
+        };
+      }),
+      withHttpLink()
+    )
+  ]
+}
+```