├── .size-limit.cjs ├── ava.config.mjs ├── siroc.config.ts ├── test ├── index.test.ts └── createPrismicLink.test.ts ├── .github ├── ISSUE_TEMPLATE │ ├── config.yml │ ├── feature_request.md │ └── bug_report.md ├── PULL_REQUEST_TEMPLATE.md ├── workflows │ └── ci.yml └── prismic-oss-ecosystem.svg ├── .gitattributes ├── .editorconfig ├── src ├── index.ts └── createPrismicLink.ts ├── .versionrc ├── tsconfig.json ├── .gitignore ├── .eslintignore ├── .prettierrc ├── .prettierignore ├── .eslintrc.cjs ├── CHANGELOG.md ├── README.md ├── package.json ├── LICENSE └── CONTRIBUTING.md /.size-limit.cjs: -------------------------------------------------------------------------------- 1 | const pkg = require("./package.json"); 2 | 3 | module.exports = [pkg.module, pkg.main] 4 | .filter(Boolean) 5 | .map((path) => ({ path })); 6 | -------------------------------------------------------------------------------- /ava.config.mjs: -------------------------------------------------------------------------------- 1 | export default { 2 | extensions: ["ts"], 3 | files: ["./test/**/*.test.ts"], 4 | require: ["ts-eager/register"], 5 | verbose: true, 6 | timeout: "60s", 7 | }; 8 | -------------------------------------------------------------------------------- /siroc.config.ts: -------------------------------------------------------------------------------- 1 | import { defineSirocConfig } from "siroc"; 2 | 3 | export default defineSirocConfig({ 4 | rollup: { 5 | output: { 6 | sourcemap: true, 7 | }, 8 | }, 9 | }); 10 | -------------------------------------------------------------------------------- /test/index.test.ts: -------------------------------------------------------------------------------- 1 | import test from "ava"; 2 | 3 | import { createPrismicLink, PrismicLink } from "../src"; 4 | 5 | test("PrismicLink is a temporary alias for createPrismicLink", (t) => { 6 | t.is(PrismicLink, createPrismicLink); 7 | }); 8 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/config.yml: -------------------------------------------------------------------------------- 1 | blank_issues_enabled: false 2 | contact_links: 3 | - name: 👪 Prismic Community Forum 4 | url: https://community.prismic.io 5 | about: Ask a question about the package or raise an issue directly related to Prismic. You will usually get support there more quickly! 6 | -------------------------------------------------------------------------------- /.gitattributes: -------------------------------------------------------------------------------- 1 | # asserts everything is text 2 | * text eol=lf 3 | 4 | # treats lock files as binaries to prevent merge headache 5 | package-lock.json -diff 6 | yarn.lock -diff 7 | 8 | # treats assets as binaries 9 | *.png binary 10 | *.jpg binary 11 | *.jpeg binary 12 | *.gif binary 13 | *.ico binary 14 | -------------------------------------------------------------------------------- /.editorconfig: -------------------------------------------------------------------------------- 1 | # editorconfig.org 2 | root = true 3 | 4 | [*] 5 | indent_style = tab 6 | end_of_line = lf 7 | charset = utf-8 8 | trim_trailing_whitespace = true 9 | insert_final_newline = true 10 | 11 | [*.md] 12 | trim_trailing_whitespace = false 13 | 14 | [*.yml] 15 | indent_style = space 16 | indent_size = 2 17 | -------------------------------------------------------------------------------- /src/index.ts: -------------------------------------------------------------------------------- 1 | import { createPrismicLink } from "./createPrismicLink"; 2 | export { createPrismicLink }; 3 | export type { PrismicLinkConfig } from "./createPrismicLink"; 4 | 5 | /** 6 | * @deprecated Use `createPrismicLink()` instead. It has the same API; only the 7 | * name is different. 8 | */ 9 | export const PrismicLink = createPrismicLink; 10 | -------------------------------------------------------------------------------- /.versionrc: -------------------------------------------------------------------------------- 1 | { 2 | "types": [ 3 | { 4 | "type": "feat", 5 | "section": "Features" 6 | }, 7 | { 8 | "type": "fix", 9 | "section": "Bug Fixes" 10 | }, 11 | { 12 | "type": "refactor", 13 | "section": "Refactor" 14 | }, 15 | { 16 | "type": "docs", 17 | "section": "Documentation" 18 | }, 19 | { 20 | "type": "chore", 21 | "section": "Chore" 22 | } 23 | ] 24 | } 25 | -------------------------------------------------------------------------------- /tsconfig.json: -------------------------------------------------------------------------------- 1 | { 2 | "compilerOptions": { 3 | "strict": true, 4 | "skipLibCheck": true, 5 | 6 | "target": "esnext", 7 | "module": "esnext", 8 | "declaration": false, 9 | "moduleResolution": "node", 10 | "resolveJsonModule": true, 11 | "allowSyntheticDefaultImports": true, 12 | "esModuleInterop": true, 13 | 14 | "forceConsistentCasingInFileNames": true, 15 | "jsx": "preserve", 16 | "lib": ["esnext", "dom"], 17 | "types": ["node"] 18 | }, 19 | "exclude": ["node_modules", "dist", "examples"] 20 | } 21 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # custom 2 | dist 3 | examples/**/package-lock.json 4 | 5 | # os 6 | .DS_Store 7 | ._* 8 | 9 | # node 10 | logs 11 | *.log 12 | node_modules 13 | 14 | # yarn 15 | yarn-debug.log* 16 | yarn-error.log* 17 | lerna-debug.log* 18 | .yarn-integrity 19 | yarn.lock 20 | 21 | # npm 22 | npm-debug.log* 23 | 24 | # tests 25 | coverage 26 | .eslintcache 27 | .nyc_output 28 | 29 | # .env 30 | .env 31 | .env.test 32 | .env*.local 33 | 34 | # vscode 35 | .vscode/* 36 | !.vscode/tasks.json 37 | !.vscode/launch.json 38 | *.code-workspace 39 | -------------------------------------------------------------------------------- /.eslintignore: -------------------------------------------------------------------------------- 1 | # .gitignore copy 2 | 3 | # custom 4 | dist 5 | examples/**/package-lock.json 6 | 7 | # os 8 | .DS_Store 9 | ._* 10 | 11 | # node 12 | logs 13 | *.log 14 | node_modules 15 | 16 | # yarn 17 | yarn-debug.log* 18 | yarn-error.log* 19 | lerna-debug.log* 20 | .yarn-integrity 21 | yarn.lock 22 | 23 | # npm 24 | npm-debug.log* 25 | 26 | # tests 27 | coverage 28 | .eslintcache 29 | .nyc_output 30 | 31 | # .env 32 | .env 33 | .env.test 34 | .env*.local 35 | 36 | # vscode 37 | .vscode/* 38 | !.vscode/tasks.json 39 | !.vscode/launch.json 40 | *.code-workspace 41 | -------------------------------------------------------------------------------- /.prettierrc: -------------------------------------------------------------------------------- 1 | { 2 | "plugins": ["prettier-plugin-jsdoc"], 3 | "jsdocSeparateReturnsFromParam": true, 4 | "jsdocSeparateTagGroups": true, 5 | "jsdocSingleLineComment": false, 6 | "tsdoc": true, 7 | "printWidth": 80, 8 | "useTabs": true, 9 | "semi": true, 10 | "singleQuote": false, 11 | "quoteProps": "as-needed", 12 | "jsxSingleQuote": false, 13 | "trailingComma": "all", 14 | "bracketSpacing": true, 15 | "bracketSameLine": false, 16 | "arrowParens": "always", 17 | "requirePragma": false, 18 | "insertPragma": false, 19 | "htmlWhitespaceSensitivity": "css", 20 | "endOfLine": "lf" 21 | } 22 | -------------------------------------------------------------------------------- /.prettierignore: -------------------------------------------------------------------------------- 1 | # custom 2 | CHANGELOG.md 3 | 4 | # .gitignore copy 5 | 6 | # custom 7 | dist 8 | examples/**/package-lock.json 9 | 10 | # os 11 | .DS_Store 12 | ._* 13 | 14 | # node 15 | logs 16 | *.log 17 | node_modules 18 | 19 | # yarn 20 | yarn-debug.log* 21 | yarn-error.log* 22 | lerna-debug.log* 23 | .yarn-integrity 24 | yarn.lock 25 | 26 | # npm 27 | npm-debug.log* 28 | 29 | # tests 30 | coverage 31 | .eslintcache 32 | .nyc_output 33 | 34 | # .env 35 | .env 36 | .env.test 37 | .env*.local 38 | 39 | # vscode 40 | .vscode/* 41 | !.vscode/tasks.json 42 | !.vscode/launch.json 43 | *.code-workspace 44 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/feature_request.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: 🙋‍♀️ Feature request 3 | about: Suggest an idea or enhancement for the package. 4 | title: "" 5 | labels: "enhancement" 6 | assignees: "" 7 | --- 8 | 9 | 10 | 11 | ### Is your feature request related to a problem? Please describe. 12 | 13 | 14 | 15 | ### Describe the solution you'd like 16 | 17 | 18 | 19 | ### Describe alternatives you've considered 20 | 21 | 22 | 23 | ### Additional context 24 | 25 | 26 | -------------------------------------------------------------------------------- /.eslintrc.cjs: -------------------------------------------------------------------------------- 1 | module.exports = { 2 | root: true, 3 | env: { 4 | browser: true, 5 | node: true, 6 | }, 7 | parserOptions: { 8 | parser: "@typescript-eslint/parser", 9 | ecmaVersion: 2020, 10 | }, 11 | extends: [ 12 | "plugin:@typescript-eslint/eslint-recommended", 13 | "plugin:@typescript-eslint/recommended", 14 | "plugin:prettier/recommended", 15 | ], 16 | plugins: ["eslint-plugin-tsdoc"], 17 | rules: { 18 | "no-console": ["warn", { allow: ["info", "warn", "error"] }], 19 | "no-debugger": "warn", 20 | "no-undef": "off", 21 | curly: "error", 22 | "prefer-const": "error", 23 | "padding-line-between-statements": [ 24 | "error", 25 | { blankLine: "always", prev: "*", next: "return" }, 26 | ], 27 | "@typescript-eslint/no-unused-vars": [ 28 | "error", 29 | { 30 | argsIgnorePattern: "^_", 31 | varsIgnorePattern: "^_", 32 | }, 33 | ], 34 | "@typescript-eslint/no-var-requires": "off", 35 | "tsdoc/syntax": "warn", 36 | }, 37 | }; 38 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/bug_report.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: 🚨 Bug report 3 | about: Report a bug report to help improve the package. 4 | title: "" 5 | labels: "bug" 6 | assignees: "" 7 | --- 8 | 9 | 16 | 17 | ### Versions 18 | 19 | - package_name: 20 | - node: 21 | 22 | ### Reproduction 23 | 24 | 25 | 26 |
27 | Additional Details 28 |
29 | 30 |
31 | 32 | ### Steps to reproduce 33 | 34 | ### What is expected? 35 | 36 | ### What is actually happening? 37 | -------------------------------------------------------------------------------- /.github/PULL_REQUEST_TEMPLATE.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | ## Types of changes 4 | 5 | 6 | 7 | - [ ] Chore (a non-breaking change which is related to package maintenance) 8 | - [ ] Bug fix (a non-breaking change which fixes an issue) 9 | - [ ] New feature (a non-breaking change which adds functionality) 10 | - [ ] Breaking change (fix or feature that would cause existing functionality to change) 11 | 12 | ## Description 13 | 14 | 15 | 16 | 17 | 18 | ## Checklist: 19 | 20 | 21 | 22 | 23 | - [ ] My change requires an update to the official documentation. 24 | - [ ] All [TSDoc](https://tsdoc.org) comments are up-to-date and new ones have been added where necessary. 25 | - [ ] All new and existing tests are passing. 26 | 27 | 28 | -------------------------------------------------------------------------------- /.github/workflows/ci.yml: -------------------------------------------------------------------------------- 1 | name: ci 2 | 3 | on: 4 | push: 5 | branches: 6 | - master 7 | pull_request: 8 | branches: 9 | - master 10 | 11 | jobs: 12 | ci: 13 | runs-on: ${{ matrix.os }} 14 | 15 | strategy: 16 | matrix: 17 | os: [ubuntu-latest] 18 | node: [14] 19 | 20 | steps: 21 | - uses: actions/setup-node@v2 22 | with: 23 | node-version: ${{ matrix.node }} 24 | 25 | - name: Checkout 26 | uses: actions/checkout@master 27 | 28 | - name: Cache node_modules 29 | uses: actions/cache@v2 30 | with: 31 | path: node_modules 32 | key: ${{ matrix.os }}-node-v${{ matrix.node }}-deps-${{ hashFiles(format('{0}{1}', github.workspace, '/package-lock.json')) }} 33 | 34 | - name: Install dependencies 35 | if: steps.cache.outputs.cache-hit != 'true' 36 | run: npm ci 37 | 38 | - name: Lint 39 | run: npm run lint 40 | 41 | - name: Unit 42 | run: npm run unit 43 | 44 | - name: Build 45 | run: npm run build 46 | 47 | - name: Coverage 48 | if: matrix.os == 'ubuntu-latest' && matrix.node == 14 49 | uses: codecov/codecov-action@v1 50 | 51 | # - name: Size 52 | # if: github.event_name == 'pull_request' && matrix.os == 'ubuntu-latest' && matrix.node == 14 53 | # uses: andresz1/size-limit-action@v1 54 | # with: 55 | # github_token: ${{ secrets.GITHUB_TOKEN }} 56 | -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # Changelog 2 | 3 | All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines. 4 | 5 | ### [1.1.2](https://github.com/prismicio/apollo-link-prismic/compare/v1.1.1...v1.1.2) (2023-06-06) 6 | 7 | 8 | ### Documentation 9 | 10 | * add missing word ([d1f3fd5](https://github.com/prismicio/apollo-link-prismic/commit/d1f3fd5df3b43cfefd254d61d4c131bcb0f12b1f)) 11 | * provide React Native-specific set up instructions ([94a2392](https://github.com/prismicio/apollo-link-prismic/commit/94a239229d96d69eee8d4b21668f91aa950c312d)) 12 | 13 | 14 | ### Refactor 15 | 16 | * update to `@prismicio/client` v7 ([#46](https://github.com/prismicio/apollo-link-prismic/issues/46)) ([a0d19d4](https://github.com/prismicio/apollo-link-prismic/commit/a0d19d4f09fcd53588791ee2595e93d2ff746c35)) 17 | 18 | ### [1.1.1](https://github.com/prismicio/apollo-link-prismic/compare/v1.1.0...v1.1.1) (2022-03-10) 19 | 20 | 21 | ### Bug Fixes 22 | 23 | * cache-bust requests using `@prismicio/client`'s updated `graphQLFetch()` ([#41](https://github.com/prismicio/apollo-link-prismic/issues/41)) ([b91c19e](https://github.com/prismicio/apollo-link-prismic/commit/b91c19e4524e420cc4d6e076e94c825b70881268)) 24 | 25 | ## [1.1.0](https://github.com/prismicio/apollo-link-prismic/compare/v1.0.9...v1.1.0) (2022-02-28) 26 | 27 | 28 | ### Features 29 | 30 | * use `@prismicio/client` v6 internally and update dependencies ([#40](https://github.com/prismicio/apollo-link-prismic/issues/40)) ([9639d2b](https://github.com/prismicio/apollo-link-prismic/commit/9639d2beeb588240cf7a5b3340ceea655e72ffd0)) 31 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # apollo-link-prismic 2 | 3 | ## Purpose 4 | 5 | An Apollo Link that allow you query Prismic's GraphQL API with [apollo-client](https://www.apollographql.com/client/). 6 | 7 | ## Installation 8 | 9 | ``` 10 | npm install apollo-link-prismic 11 | ``` 12 | 13 | ## Usage 14 | 15 | ```typescript 16 | import { ApolloClient, InMemoryCache } from "@apollo/client"; 17 | import { createPrismicLink } from "apollo-link-prismic"; 18 | 19 | const apolloClient = new ApolloClient({ 20 | link: createPrismicLink({ 21 | repositoryName: "YOUR_REPOSITORY_NAME", 22 | // Provide your access token if your repository is secured. 23 | accessToken: "YOUR_ACCESS_TOKEN", 24 | }), 25 | cache: new InMemoryCache(), 26 | }); 27 | ``` 28 | 29 | ### Providing a `fetch` function 30 | 31 | If you are using this link in an environment where a global `fetch` function does not exist, such as Node.js, you must provide one using the `fetch` option. 32 | 33 | Environments like the browser, [Next.js](https://nextjs.org/), [Cloudflare Workers](https://workers.cloudflare.com/), and [Remix](https://remix.run/) provide a global `fetch` function and do not require passing your own. 34 | 35 | There are many libraries that can provide this function. The most common is [`node-fetch`](https://www.npmjs.com/package/node-fetch), which you would configure like this: 36 | 37 | ```typescript 38 | import { ApolloClient, InMemoryCache } from "@apollo/client"; 39 | import { createPrismicLink } from "apollo-link-prismic"; 40 | import fetch from "node-fetch"; 41 | 42 | const apolloClient = new ApolloClient({ 43 | link: createPrismicLink({ 44 | repositoryName: "YOUR_REPOSITORY_NAME", 45 | // Provide your access token if your repository is secured. 46 | accessToken: "YOUR_ACCESS_TOKEN", 47 | fetch, 48 | }), 49 | cache: new InMemoryCache(), 50 | }); 51 | ``` 52 | 53 | ### Installation with React Native 54 | 55 | Using `apollo-link-prismic` in React Native applications requires additional setup. 56 | 57 | After installing `apollo-link-prismic`, install the following [URL Web API](https://developer.mozilla.org/en-US/docs/Web/API/URL_API) polyfill: 58 | 59 | ```sh 60 | npm install react-native-url-polyfill 61 | ``` 62 | 63 | Next, import the polyfill in your app’s entry file (typically this is App.js or index.js). 64 | 65 | ```javascript 66 | // App.js or index.js 67 | 68 | import "react-native-url-polyfill/auto"; 69 | ``` 70 | 71 | `apollo-link-prismic` can now be used throughout your app. 72 | 73 | **Note**: If the polyfill does not work after importing in your app's entry file, try the alternative ["Flexible" set up method described in `react-native-url-polyfill`'s documentation](https://github.com/charpeni/react-native-url-polyfill#option-2-flexible). 74 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "apollo-link-prismic", 3 | "version": "1.1.2", 4 | "description": "Apollo link for Prismic", 5 | "keywords": [ 6 | "graphql", 7 | "apollo", 8 | "link", 9 | "prismic" 10 | ], 11 | "homepage": "https://github.com/prismicio/apollo-link-prismic#readme", 12 | "bugs": { 13 | "url": "https://github.com/prismicio/apollo-link-prismic/issues" 14 | }, 15 | "repository": { 16 | "type": "git", 17 | "url": "https://github.com/prismicio/apollo-link-prismic.git" 18 | }, 19 | "license": "Apache-2.0", 20 | "author": "Prismic (https://prismic.io)", 21 | "sideEffects": false, 22 | "exports": { 23 | ".": { 24 | "require": "./dist/index.cjs", 25 | "import": "./dist/index.js" 26 | }, 27 | "./package.json": "./package.json" 28 | }, 29 | "main": "dist/index.cjs", 30 | "module": "dist/index.js", 31 | "types": "dist/index.d.ts", 32 | "files": [ 33 | "dist", 34 | "src" 35 | ], 36 | "scripts": { 37 | "build": "siroc build", 38 | "dev": "siroc build --watch", 39 | "format": "prettier --write .", 40 | "lint": "eslint --ext .js,.ts .", 41 | "prepare": "npm run build", 42 | "release": "npm run test && standard-version && git push --follow-tags && npm run build && npm publish", 43 | "release:alpha": "npm run test && standard-version --release-as major --prerelease alpha && git push --follow-tags && npm run build && npm publish --tag alpha", 44 | "release:alpha:dry": "standard-version --release-as major --prerelease alpha --dry-run", 45 | "release:dry": "standard-version --dry-run", 46 | "size": "size-limit", 47 | "test": "npm run lint && npm run unit && npm run build && npm run size", 48 | "unit": "nyc --reporter=lcovonly --reporter=text --exclude-after-remap=false ava" 49 | }, 50 | "dependencies": { 51 | "@prismicio/client": "^7.0.1" 52 | }, 53 | "devDependencies": { 54 | "@apollo/client": "^3.5.8", 55 | "@size-limit/preset-small-lib": "^7.0.8", 56 | "@types/node-fetch": "^2.6.0", 57 | "@types/sinon": "^10.0.11", 58 | "@typescript-eslint/eslint-plugin": "^5.12.0", 59 | "@typescript-eslint/parser": "^5.12.0", 60 | "ava": "^4.0.1", 61 | "eslint": "^8.9.0", 62 | "eslint-config-prettier": "^8.3.0", 63 | "eslint-plugin-prettier": "^4.0.0", 64 | "eslint-plugin-tsdoc": "^0.2.14", 65 | "graphql": "^16.3.0", 66 | "node-fetch": "^2.6.7", 67 | "nyc": "^15.1.0", 68 | "prettier": "^2.5.1", 69 | "prettier-plugin-jsdoc": "^0.3.30", 70 | "sinon": "^13.0.1", 71 | "siroc": "^0.16.0", 72 | "size-limit": "^7.0.8", 73 | "standard-version": "^9.3.2", 74 | "ts-eager": "^2.0.2", 75 | "typescript": "^4.5.5" 76 | }, 77 | "peerDependencies": { 78 | "@apollo/client": "^3" 79 | }, 80 | "engines": { 81 | "node": ">=12.7.0" 82 | }, 83 | "publishConfig": { 84 | "access": "public" 85 | } 86 | } 87 | -------------------------------------------------------------------------------- /src/createPrismicLink.ts: -------------------------------------------------------------------------------- 1 | import type { ApolloLink, HttpOptions } from "@apollo/client/core"; 2 | import { createHttpLink } from "@apollo/client/core"; 3 | import { 4 | FetchLike, 5 | getRepositoryName, 6 | getRepositoryEndpoint, 7 | getGraphQLEndpoint, 8 | createClient, 9 | } from "@prismicio/client"; 10 | 11 | /** 12 | * Configuration for `createPrismicLink`. 13 | */ 14 | export type PrismicLinkConfig = Omit< 15 | HttpOptions, 16 | "fetch" | "useGETForQueries" 17 | > & 18 | ( 19 | | { 20 | /** 21 | * The name of the link's Prismic repository. 22 | */ 23 | repositoryName: string; 24 | 25 | /** 26 | * The GraphQL API endpoint for the link's Prismic repository. If a 27 | * value is not given, the link will use the default Prismic GraphQL API 28 | * endpoint for the link's Prismic repository using the `repositoryName` 29 | * parameter. 30 | */ 31 | uri?: string; 32 | } 33 | | { 34 | /** 35 | * The name of the link's Prismic repository. 36 | */ 37 | repositoryName?: string; 38 | 39 | /** 40 | * The GraphQL API endpoint for the link's Prismic repository. If a 41 | * value is not given, the link will use the default Prismic GraphQL API 42 | * endpoint for the link's Prismic repository using the `repositoryName` 43 | * parameter. 44 | */ 45 | uri: string; 46 | } 47 | ) & { 48 | /** 49 | * The access token for the link's Prismic repository. 50 | */ 51 | accessToken?: string; 52 | 53 | /** 54 | * The Rest API endpoint for the link's Prismic repository. If a value is 55 | * not given, the link will use the default Prismic Rest API endpoint for 56 | * the link's Prismic repository using the `repositoryName` parameter. 57 | */ 58 | apiEndpoint?: string; 59 | 60 | /** 61 | * The function used to make network requests to the Prismic API. In 62 | * environments where a global `fetch` function does not exist, such as 63 | * Node.js, this function must be provided. 64 | */ 65 | fetch?: FetchLike; 66 | }; 67 | 68 | /** 69 | * Creates an Apollo Link that sends GraphQL queries to a Prismic repository's 70 | * GraphQL API. 71 | * 72 | * @example 73 | * 74 | * ```ts 75 | * import { ApolloClient, InMemoryCache } from "@apollo/client"; 76 | * import { createPrismicLink } from "apollo-link-prismic"; 77 | * 78 | * const client = new ApolloClient({ 79 | * link: createPrismicLink({ 80 | * repositoryName: "your-repo-name", 81 | * // Provide an access token if the repository is secured. 82 | * accessToken: "example-access-token", 83 | * }), 84 | * cache: new InMemoryCache(), 85 | * }); 86 | * ``` 87 | * 88 | * @param config - Configuration for the Prismic Link. 89 | * 90 | * @returns An Apollo Link for the configured Prismic repository's GraphQL API. 91 | */ 92 | export const createPrismicLink = (config: PrismicLinkConfig): ApolloLink => { 93 | const { 94 | repositoryName: providedRepositoryName, 95 | fetch, 96 | accessToken, 97 | apiEndpoint: providedApiEndpoint, 98 | uri: providedURI, 99 | ...options 100 | } = config; 101 | 102 | let repositoryName = providedRepositoryName; 103 | 104 | if (!repositoryName && providedURI) { 105 | repositoryName = getRepositoryName(providedURI); 106 | } 107 | 108 | if (!repositoryName) { 109 | throw new Error( 110 | "At least one of the following options are required for createPrismicLink(): repositoryName, uri. If a repositoryName option is not given, the uri option must be a standard, non-proxied Prismic GraphQL API URL including the repository name.", 111 | ); 112 | } 113 | 114 | const uri = providedURI || getGraphQLEndpoint(repositoryName); 115 | const apiEndpoint = 116 | providedApiEndpoint || getRepositoryEndpoint(repositoryName); 117 | 118 | const client = createClient(apiEndpoint, { 119 | fetch, 120 | accessToken, 121 | }); 122 | 123 | return createHttpLink({ 124 | uri, 125 | fetch: client.graphQLFetch, 126 | useGETForQueries: true, 127 | ...options, 128 | }); 129 | }; 130 | -------------------------------------------------------------------------------- /test/createPrismicLink.test.ts: -------------------------------------------------------------------------------- 1 | import test from "ava"; 2 | import { 3 | ApolloLink, 4 | execute, 5 | FetchResult, 6 | gql, 7 | GraphQLRequest, 8 | } from "@apollo/client/core"; 9 | import { Response } from "node-fetch"; 10 | import * as sinon from "sinon"; 11 | import * as prismic from "@prismicio/client"; 12 | import * as prismicT from "@prismicio/types"; 13 | 14 | import { createPrismicLink } from "../src"; 15 | 16 | interface LinkResult { 17 | result: FetchResult; 18 | } 19 | 20 | const executeRequest = ( 21 | link: ApolloLink, 22 | request: GraphQLRequest, 23 | ) => { 24 | const linkResult = {} as LinkResult; 25 | 26 | return new Promise>((resolve, reject) => { 27 | execute(link, request).subscribe( 28 | (result) => { 29 | linkResult.result = result as FetchResult; 30 | }, 31 | (error) => { 32 | reject(error); 33 | }, 34 | () => { 35 | resolve(linkResult); 36 | }, 37 | ); 38 | }); 39 | }; 40 | 41 | const repositoryResponse: Partial = { 42 | refs: [ 43 | { 44 | ref: "master", 45 | isMasterRef: true, 46 | id: "master", 47 | label: "Master", 48 | }, 49 | ], 50 | }; 51 | const ref = repositoryResponse.refs?.[0].ref as string; 52 | 53 | test("creates an HTTP Link from a repositoryName", async (t) => { 54 | const repositoryName = "qwerty"; 55 | const apiEndpoint = prismic.getRepositoryEndpoint(repositoryName); 56 | const uri = prismic.getGraphQLEndpoint(repositoryName); 57 | 58 | const query = gql` 59 | query { 60 | foo 61 | } 62 | `; 63 | const compressedQuery = `{foo}`; 64 | 65 | const fetch = sinon.stub().callsFake(async (url) => { 66 | const instance = new URL(url); 67 | 68 | if (url === apiEndpoint) { 69 | return new Response(JSON.stringify(repositoryResponse)); 70 | } else if (`${instance.origin}${instance.pathname}` === uri) { 71 | t.is(instance.searchParams.get("query"), compressedQuery); 72 | t.is(instance.searchParams.get("ref"), ref); 73 | 74 | return new Response( 75 | JSON.stringify({ 76 | data: { 77 | foo: "bar", 78 | }, 79 | }), 80 | ); 81 | } else { 82 | return new Response("{}", { status: 404 }); 83 | } 84 | }); 85 | 86 | const link = createPrismicLink({ 87 | repositoryName, 88 | fetch, 89 | }); 90 | 91 | await executeRequest(link, { query }); 92 | 93 | t.plan(2); 94 | }); 95 | 96 | test("supports only a uri option", async (t) => { 97 | const repositoryName = "qwerty"; 98 | const apiEndpoint = prismic.getRepositoryEndpoint(repositoryName); 99 | const uri = prismic.getGraphQLEndpoint(repositoryName); 100 | 101 | const query = gql` 102 | query { 103 | foo 104 | } 105 | `; 106 | const compressedQuery = `{foo}`; 107 | 108 | const fetch = sinon.stub().callsFake(async (url) => { 109 | const instance = new URL(url); 110 | 111 | if (url === apiEndpoint) { 112 | return new Response(JSON.stringify(repositoryResponse)); 113 | } else if (`${instance.origin}${instance.pathname}` === uri) { 114 | t.is(instance.searchParams.get("query"), compressedQuery); 115 | t.is(instance.searchParams.get("ref"), ref); 116 | 117 | return new Response( 118 | JSON.stringify({ 119 | data: { 120 | foo: "bar", 121 | }, 122 | }), 123 | ); 124 | } else { 125 | return new Response("{}", { status: 404 }); 126 | } 127 | }); 128 | 129 | const link = createPrismicLink({ 130 | uri, 131 | fetch, 132 | }); 133 | 134 | await executeRequest(link, { query }); 135 | 136 | t.plan(2); 137 | }); 138 | 139 | test("throws if neither a repositoryName or uri option is given", (t) => { 140 | t.throws( 141 | () => { 142 | createPrismicLink( 143 | // @ts-expect-error - Purposely leaving off a repositoryName and uri option to throw the runtime error. 144 | { 145 | fetch: sinon.stub(), 146 | }, 147 | ); 148 | }, 149 | { 150 | message: 151 | /At least one of the following options are required for createPrismicLink\(\): repositoryName, uri/, 152 | }, 153 | ); 154 | }); 155 | 156 | test("supports custom API endpoint (for Rest API)", async (t) => { 157 | const repositoryName = "qwerty"; 158 | const apiEndpoint = "https://example.com/"; 159 | const uri = prismic.getGraphQLEndpoint(repositoryName); 160 | 161 | const query = gql` 162 | query { 163 | foo 164 | } 165 | `; 166 | const compressedQuery = `{foo}`; 167 | 168 | const fetch = sinon.stub().callsFake(async (url) => { 169 | const instance = new URL(url); 170 | 171 | if (url === apiEndpoint) { 172 | return new Response(JSON.stringify(repositoryResponse)); 173 | } else if (`${instance.origin}${instance.pathname}` === uri) { 174 | t.is(instance.searchParams.get("query"), compressedQuery); 175 | t.is(instance.searchParams.get("ref"), ref); 176 | 177 | return new Response( 178 | JSON.stringify({ 179 | data: { 180 | foo: "bar", 181 | }, 182 | }), 183 | ); 184 | } else { 185 | return new Response("{}", { status: 404 }); 186 | } 187 | }); 188 | 189 | const link = createPrismicLink({ 190 | repositoryName, 191 | apiEndpoint, 192 | fetch, 193 | }); 194 | 195 | await executeRequest(link, { query }); 196 | 197 | t.plan(2); 198 | }); 199 | 200 | test("supports custom GraphQL endpoint", async (t) => { 201 | const repositoryName = "qwerty"; 202 | const apiEndpoint = prismic.getRepositoryEndpoint(repositoryName); 203 | const uri = "https://example.com/"; 204 | 205 | const query = gql` 206 | query { 207 | foo 208 | } 209 | `; 210 | const compressedQuery = `{foo}`; 211 | 212 | const fetch = sinon.stub().callsFake(async (url) => { 213 | const instance = new URL(url); 214 | 215 | if (url === apiEndpoint) { 216 | return new Response(JSON.stringify(repositoryResponse)); 217 | } else if (`${instance.origin}${instance.pathname}` === uri) { 218 | t.is(instance.searchParams.get("query"), compressedQuery); 219 | t.is(instance.searchParams.get("ref"), ref); 220 | 221 | return new Response( 222 | JSON.stringify({ 223 | data: { 224 | foo: "bar", 225 | }, 226 | }), 227 | ); 228 | } else { 229 | return new Response("{}", { status: 404 }); 230 | } 231 | }); 232 | 233 | const link = createPrismicLink({ 234 | repositoryName, 235 | uri, 236 | fetch, 237 | }); 238 | 239 | await executeRequest(link, { query }); 240 | 241 | t.plan(2); 242 | }); 243 | -------------------------------------------------------------------------------- /.github/prismic-oss-ecosystem.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | 2 | Apache License 3 | Version 2.0, January 2004 4 | http://www.apache.org/licenses/ 5 | 6 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 7 | 8 | 1. Definitions. 9 | 10 | "License" shall mean the terms and conditions for use, reproduction, 11 | and distribution as defined by Sections 1 through 9 of this document. 12 | 13 | "Licensor" shall mean the copyright owner or entity authorized by 14 | the copyright owner that is granting the License. 15 | 16 | "Legal Entity" shall mean the union of the acting entity and all 17 | other entities that control, are controlled by, or are under common 18 | control with that entity. For the purposes of this definition, 19 | "control" means (i) the power, direct or indirect, to cause the 20 | direction or management of such entity, whether by contract or 21 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 22 | outstanding shares, or (iii) beneficial ownership of such entity. 23 | 24 | "You" (or "Your") shall mean an individual or Legal Entity 25 | exercising permissions granted by this License. 26 | 27 | "Source" form shall mean the preferred form for making modifications, 28 | including but not limited to software source code, documentation 29 | source, and configuration files. 30 | 31 | "Object" form shall mean any form resulting from mechanical 32 | transformation or translation of a Source form, including but 33 | not limited to compiled object code, generated documentation, 34 | and conversions to other media types. 35 | 36 | "Work" shall mean the work of authorship, whether in Source or 37 | Object form, made available under the License, as indicated by a 38 | copyright notice that is included in or attached to the work 39 | (an example is provided in the Appendix below). 40 | 41 | "Derivative Works" shall mean any work, whether in Source or Object 42 | form, that is based on (or derived from) the Work and for which the 43 | editorial revisions, annotations, elaborations, or other modifications 44 | represent, as a whole, an original work of authorship. For the purposes 45 | of this License, Derivative Works shall not include works that remain 46 | separable from, or merely link (or bind by name) to the interfaces of, 47 | the Work and Derivative Works thereof. 48 | 49 | "Contribution" shall mean any work of authorship, including 50 | the original version of the Work and any modifications or additions 51 | to that Work or Derivative Works thereof, that is intentionally 52 | submitted to Licensor for inclusion in the Work by the copyright owner 53 | or by an individual or Legal Entity authorized to submit on behalf of 54 | the copyright owner. For the purposes of this definition, "submitted" 55 | means any form of electronic, verbal, or written communication sent 56 | to the Licensor or its representatives, including but not limited to 57 | communication on electronic mailing lists, source code control systems, 58 | and issue tracking systems that are managed by, or on behalf of, the 59 | Licensor for the purpose of discussing and improving the Work, but 60 | excluding communication that is conspicuously marked or otherwise 61 | designated in writing by the copyright owner as "Not a Contribution." 62 | 63 | "Contributor" shall mean Licensor and any individual or Legal Entity 64 | on behalf of whom a Contribution has been received by Licensor and 65 | subsequently incorporated within the Work. 66 | 67 | 2. Grant of Copyright License. Subject to the terms and conditions of 68 | this License, each Contributor hereby grants to You a perpetual, 69 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 70 | copyright license to reproduce, prepare Derivative Works of, 71 | publicly display, publicly perform, sublicense, and distribute the 72 | Work and such Derivative Works in Source or Object form. 73 | 74 | 3. Grant of Patent License. Subject to the terms and conditions of 75 | this License, each Contributor hereby grants to You a perpetual, 76 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 77 | (except as stated in this section) patent license to make, have made, 78 | use, offer to sell, sell, import, and otherwise transfer the Work, 79 | where such license applies only to those patent claims licensable 80 | by such Contributor that are necessarily infringed by their 81 | Contribution(s) alone or by combination of their Contribution(s) 82 | with the Work to which such Contribution(s) was submitted. If You 83 | institute patent litigation against any entity (including a 84 | cross-claim or counterclaim in a lawsuit) alleging that the Work 85 | or a Contribution incorporated within the Work constitutes direct 86 | or contributory patent infringement, then any patent licenses 87 | granted to You under this License for that Work shall terminate 88 | as of the date such litigation is filed. 89 | 90 | 4. Redistribution. You may reproduce and distribute copies of the 91 | Work or Derivative Works thereof in any medium, with or without 92 | modifications, and in Source or Object form, provided that You 93 | meet the following conditions: 94 | 95 | (a) You must give any other recipients of the Work or 96 | Derivative Works a copy of this License; and 97 | 98 | (b) You must cause any modified files to carry prominent notices 99 | stating that You changed the files; and 100 | 101 | (c) You must retain, in the Source form of any Derivative Works 102 | that You distribute, all copyright, patent, trademark, and 103 | attribution notices from the Source form of the Work, 104 | excluding those notices that do not pertain to any part of 105 | the Derivative Works; and 106 | 107 | (d) If the Work includes a "NOTICE" text file as part of its 108 | distribution, then any Derivative Works that You distribute must 109 | include a readable copy of the attribution notices contained 110 | within such NOTICE file, excluding those notices that do not 111 | pertain to any part of the Derivative Works, in at least one 112 | of the following places: within a NOTICE text file distributed 113 | as part of the Derivative Works; within the Source form or 114 | documentation, if provided along with the Derivative Works; or, 115 | within a display generated by the Derivative Works, if and 116 | wherever such third-party notices normally appear. The contents 117 | of the NOTICE file are for informational purposes only and 118 | do not modify the License. You may add Your own attribution 119 | notices within Derivative Works that You distribute, alongside 120 | or as an addendum to the NOTICE text from the Work, provided 121 | that such additional attribution notices cannot be construed 122 | as modifying the License. 123 | 124 | You may add Your own copyright statement to Your modifications and 125 | may provide additional or different license terms and conditions 126 | for use, reproduction, or distribution of Your modifications, or 127 | for any such Derivative Works as a whole, provided Your use, 128 | reproduction, and distribution of the Work otherwise complies with 129 | the conditions stated in this License. 130 | 131 | 5. Submission of Contributions. Unless You explicitly state otherwise, 132 | any Contribution intentionally submitted for inclusion in the Work 133 | by You to the Licensor shall be under the terms and conditions of 134 | this License, without any additional terms or conditions. 135 | Notwithstanding the above, nothing herein shall supersede or modify 136 | the terms of any separate license agreement you may have executed 137 | with Licensor regarding such Contributions. 138 | 139 | 6. Trademarks. This License does not grant permission to use the trade 140 | names, trademarks, service marks, or product names of the Licensor, 141 | except as required for reasonable and customary use in describing the 142 | origin of the Work and reproducing the content of the NOTICE file. 143 | 144 | 7. Disclaimer of Warranty. Unless required by applicable law or 145 | agreed to in writing, Licensor provides the Work (and each 146 | Contributor provides its Contributions) on an "AS IS" BASIS, 147 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 148 | implied, including, without limitation, any warranties or conditions 149 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 150 | PARTICULAR PURPOSE. You are solely responsible for determining the 151 | appropriateness of using or redistributing the Work and assume any 152 | risks associated with Your exercise of permissions under this License. 153 | 154 | 8. Limitation of Liability. In no event and under no legal theory, 155 | whether in tort (including negligence), contract, or otherwise, 156 | unless required by applicable law (such as deliberate and grossly 157 | negligent acts) or agreed to in writing, shall any Contributor be 158 | liable to You for damages, including any direct, indirect, special, 159 | incidental, or consequential damages of any character arising as a 160 | result of this License or out of the use or inability to use the 161 | Work (including but not limited to damages for loss of goodwill, 162 | work stoppage, computer failure or malfunction, or any and all 163 | other commercial damages or losses), even if such Contributor 164 | has been advised of the possibility of such damages. 165 | 166 | 9. Accepting Warranty or Additional Liability. While redistributing 167 | the Work or Derivative Works thereof, You may choose to offer, 168 | and charge a fee for, acceptance of support, warranty, indemnity, 169 | or other liability obligations and/or rights consistent with this 170 | License. However, in accepting such obligations, You may act only 171 | on Your own behalf and on Your sole responsibility, not on behalf 172 | of any other Contributor, and only if You agree to indemnify, 173 | defend, and hold each Contributor harmless for any liability 174 | incurred by, or claims asserted against, such Contributor by reason 175 | of your accepting any such warranty or additional liability. 176 | 177 | END OF TERMS AND CONDITIONS 178 | 179 | APPENDIX: How to apply the Apache License to your work. 180 | 181 | To apply the Apache License to your work, attach the following 182 | boilerplate notice, with the fields enclosed by brackets "[]" 183 | replaced with your own identifying information. (Don't include 184 | the brackets!) The text should be enclosed in the appropriate 185 | comment syntax for the file format. We also recommend that a 186 | file or class name and description of purpose be included on the 187 | same "printed page" as the copyright notice for easier 188 | identification within third-party archives. 189 | 190 | Copyright [yyyy] [name of copyright owner] 191 | 192 | Licensed under the Apache License, Version 2.0 (the "License"); 193 | you may not use this file except in compliance with the License. 194 | You may obtain a copy of the License at 195 | 196 | http://www.apache.org/licenses/LICENSE-2.0 197 | 198 | Unless required by applicable law or agreed to in writing, software 199 | distributed under the License is distributed on an "AS IS" BASIS, 200 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 201 | See the License for the specific language governing permissions and 202 | limitations under the License. 203 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing to Prismic 2 | 3 | This document is aimed at providing developers (mainly maintainers) documentation on this project and its structure. It is not intended to pass requirements for contributing to this project. 4 | 5 | For the latter, the [Quick Start](#quick-start) section below can help you. You are free to [open issues][repo-issue] and [submit pull requests][repo-pull-requests] toward the `master` branch directly without worrying about our standards. For pull requests, we will help you through our merging process. 6 | 7 | > For a Table of Contents, use GitHub's TOC button, top left of the document. 8 | 9 | ## Quick Start 10 | 11 | ```bash 12 | # First, fork the repository to your GitHub account if you aren't an existing maintainer 13 | 14 | # Clone your fork 15 | git clone git@github.com:/apollo-link-prismic.git 16 | 17 | # Create a feature branch with your initials and feature name 18 | git checkout -b / # e.g. `lh/fix-win32-paths` 19 | 20 | # Install dependencies with npm 21 | npm install 22 | 23 | # Test your changes 24 | npm run test 25 | 26 | # Commit your changes once they are ready 27 | # Conventional Commits are encouraged, but not required 28 | git add . 29 | git commit -m "short description of your changes" 30 | 31 | # Lastly, open a pull request on GitHub describing your changes 32 | ``` 33 | 34 | ## Processes 35 | 36 | Processes refer to tasks that you may need to perform while working on this project. 37 | 38 | ### Developing 39 | 40 | There is no development branch. The `master` branch refers to the latest [stable (living) version](#stable-xxx) of the project and pull requests should be made against it. 41 | 42 | If development on a [new major version](#iteration-cycle) has begun, a branch named after the major version will be created (e.g. `v2` for work on the future `v2.0.0` of the project). Pull requests targeting that new major version should be made against it. 43 | 44 | To develop locally: 45 | 46 | 1. **If you have maintainer access**:
[Clone the repository](https://help.github.com/articles/cloning-a-repository) to your local environment. 47 | 48 | **If you do no have maintainer access**:
[Fork](https://help.github.com/articles/fork-a-repo) and [clone](https://help.github.com/articles/cloning-a-repository) the repository to your local environment. 49 | 50 | 2. Create a new branch: 51 | 52 | ```bash 53 | git checkout -b / # e.g. `aa/graphql-support` 54 | ``` 55 | 56 | 3. Install dependencies with [npm][npm] (avoid using [Yarn][yarn]): 57 | 58 | ```bash 59 | npm install 60 | ``` 61 | 62 | 4. Start developing: 63 | 64 | ```bash 65 | npm run dev 66 | ``` 67 | 68 | 5. Commit your changes: 69 | 70 | If you already know the [Conventional Commits convention][conventional-commits], feel free to embrace it for your commit messages. If you don't, no worries; it can always be taken care of when the pull request is merged. 71 | 72 | ### Building 73 | 74 | Our build system is handled by [siroc][siroc], a near-zero-config build tool powered by [esbuild](https://github.com/evanw/esbuild). It takes care of: 75 | 76 | - Generating a [CommonJS (`.cjs`)](https://nodejs.org/docs/latest/api/modules.html#modules_modules_commonjs_modules) bundle and its source map; 77 | - Generating an [ECMAScript (`.mjs`)](https://nodejs.org/docs/latest/api/modules.html#modules_modules_commonjs_modules) bundle and its source map; 78 | - Generating a TypeScript declaration (`.d.ts`) file. 79 | 80 | To build the project: 81 | 82 | ```bash 83 | npm run build 84 | ``` 85 | 86 | The CI system will try to build the project on each commit targeting the `master` branch. The CI check will fail if the build does. 87 | 88 | ### Testing 89 | 90 | All projects have at least linting and unit tests. Linting is handled by [ESLint][eslint] with [Prettier][prettier] and unit tests are handled by [AVA][ava]. 91 | 92 | To run all tests: 93 | 94 | ```bash 95 | npm run test 96 | ``` 97 | 98 | If you'd like to run only the linter (note that it won't reformat your code; use the `format` script for that): 99 | 100 | ```bash 101 | npm run lint 102 | ``` 103 | 104 | If you'd like to run only the unit tests: 105 | 106 | ```bash 107 | npm run unit 108 | ``` 109 | 110 | If you'd like to run only the unit tests in watch mode (re-runs tests each time a file is saved): 111 | 112 | ```bash 113 | npm run unit -- --watch 114 | ``` 115 | 116 | When working on unit tests, you might want to update snapshots (be careful when doing so): 117 | 118 | ```bash 119 | npm run unit -- --update-snapshots 120 | ``` 121 | 122 | The CI system will run tests on each commit targeting the `master` branch. The CI check will fail if any test does. 123 | 124 | ### Publishing 125 | 126 | > ⚠  Only project maintainers with at least collaborator access to the related npm package can publish new versions. 127 | 128 | Publishing a package correctly involves multiple steps: 129 | 130 | - Writing a changelog; 131 | - [Building](#building) the project; 132 | - Publishing a new version tag to GitHub; 133 | - Publishing build artifacts to [npm][npm]. 134 | 135 | In order to make sure all these steps are consistently and correctly done, we use [Standard Version][standard-version] and build scripts. 136 | 137 | To release a new version of the project: 138 | 139 | ```bash 140 | npm run release 141 | ``` 142 | 143 | To release a new [alpha](#alpha-xxx-alphax) version of the project: 144 | 145 | ```bash 146 | npm run release:alpha 147 | ``` 148 | 149 | Those scripts will: 150 | 151 | - Run tests and try to build the project; 152 | - Figure out the new version number by looking at commit messages matching the [Conventional Commits convention][conventional-commits]; 153 | - Write the [changelog][changelog] for the new version after Conventional Commit messages; 154 | - Build the project for publishing; 155 | - Publish a new version tag to GitHub; 156 | - Publish build artifacts to [npm][npm]. 157 | 158 | If you ran any of those commands but happen not to have access to the related npm package, you can still ask a collaborator of the said package to publish it for you. 159 | 160 | Appending `:dry` (e.g. `release:dry`) to any of the above commands will dry-run the targeted release script and output the new changelog to the console. 161 | 162 | We consider [maintaining](#maintaining) project dependencies before publishing a new version a best practice. 163 | 164 | ### Maintaining 165 | 166 | We actively maintain a [TypeScript template][template] with Prismic's latest open-source standards. Keeping every project in sync with this template is nearly impossible so we're not trying to immediately reflect changes to the template in every project. Instead we consider a best practice to manually pull changes from the template into the project whenever someone is doing project maintenance and has time for it, or wants to enjoy the latest standards from it. 167 | 168 | ## `package_name` in Prismic's Open-Source Ecosystem 169 | 170 | Prismic's Open-Source ecosystem is built around a 3-stage pyramid: 171 | 172 |

173 | Prismic open-source pyramid 174 |

175 | 176 | Where: 177 | 178 | - **Core**: Represents libraries providing core Prismic integration such as data fetching and content transformation, e.g. [`@prismicio/client`](https://github.com/prismicio/prismic-client); 179 | - **Integration**: Represents libraries to integration into UI libraries. They must be framework agnostic, e.g. [`@prismicio/react`](https://github.com/prismicio/prismic-react); 180 | - **Framework**: Represents libraries to integrate into frameworks, including data fetching and normalizing. They must follow frameworks' expected practices, e.g. [`@prismicio/next`](https://github.com/prismicio/prismic-next). 181 | 182 | 183 | 184 | 185 | 186 | 187 | 188 | ## Iteration Cycle 189 | 190 | We break iteration cycle of a project's library into 4 phases: 191 | 192 | - **Pre-alpha** 193 | - **Alpha** 194 | - **Beta** 195 | - **Stable** 196 | 197 | ### Pre-alpha 198 | 199 | > At any point we might feel the need to introduce breaking changes to a project's library (getting rid of legacy APIs, embracing latest features from a framework, etc.). When such a need has been identified for a project, it will enter the pre-alpha phase. The project might also enter the pre-alpha phase for large, non-breaking changes that need more planning and thoughts. 200 | > 201 | > The goal of the pre-alpha phase is to design and share the new project's library API through an RFC. Under certain circumstances (e.g. the API has already been clearly defined in another language and only some adaptations have to be made), the project can skip the pre-alpha phase and enter the alpha phase directly. Skipping the pre-alpha phase should be treated as an exception. 202 | 203 | During the pre-alpha phase, the following will happen: 204 | 205 | **Documenting and understanding the library's current functionality:** 206 | 207 | Doing so leads to a better understanding of the library's current functionality and limitations. Reviewing GitHub Issues will provide insight into existing bugs and user requests. We want to reduce the number of breaking changes where possible while not being afraid to do so if necessary. 208 | 209 | **Sketching the API in code, examples, and written explanations:** 210 | 211 | The library should be written in concept before its concrete implementation. This frees us from technical limitations and implementation details. It also allows us to craft the best feeling API. 212 | 213 | **Writing the public RFC:** 214 | 215 | A formal RFC should be posted publicly once the initial brainstorming session is complete that focuses on new and changed concepts. This allows everyone to read and voice their opinions should they choose to. 216 | 217 | ### Alpha (`x.x.x-alpha.x`) 218 | 219 | > As soon as the RFC has been posted, the project enters the alpha phase. 220 | > 221 | > The goal of the alpha phase is to implement the new project's library API, to test it, and to document it. 222 | 223 | During the alpha phase, the following will happen: 224 | 225 | **Writing the implementation:** 226 | 227 | The implementation must be done in TypeScript and include extensive tests and in-code documentation. Generally the process goes as follows: 228 | 229 | 1. Writing the implementation in TypeScript; 230 | 2. Testing the implementation; 231 | 3. Documenting the implementation with TSDocs (at least all publicly exported APIs). 232 | 233 | **Publishing public alpha versions:** 234 | 235 | Publishing alpha versions of the library allows for easier internal testing. With alpha versions, users can test the library as it is published publicly, however those versions are not recommended or shared extensively as breaking changes are still very likely to occur and the library is still not documented. Alpha versions can be published as often as needed. 236 | 237 | **Adjusting per internal and external feedback:** 238 | 239 | An internal code review should be performed. As users use the alpha, issues will be opened for bugs and suggestions. Appropriate adjustments to the library should be made with a focus on doing what users expect while minimizing technical debt. For that purpose, breaking changes to the new API can be introduced. 240 | 241 | **Updating documentation:** 242 | 243 | Documentation for the library should be updated on [prismic.io][prismic-docs] and is treated as the primary source of documentation. Contributors will work closely with Prismic Education team to complete this. This involves updating related documentation and code examples as well, including any starter projects on GitHub. A migration guide should be included if necessary. 244 | 245 | ### Beta (`x.x.x-beta.x`) 246 | 247 | > As soon as the implementation is completed and the updated documentation is ready to be published, the project enters the beta phase. 248 | > 249 | > The goal of the beta phase is to test the updated library's API by publicly sharing it with the community and receiving early adopters' feedback. The beta phase is the last opportunity for breaking changes to be introduced. 250 | 251 | During the beta phase, the following will happen: 252 | 253 | **Publishing public beta versions and related documentation:** 254 | 255 | A first beta should be published along the related documentation that has been worked on during the alpha phase. This release should be announced and shared to users in order to get feedback from early adopters. Subsequent beta versions can be published as often as needed, but we have to keep in mind users are now expected to be using them. 256 | 257 | **Adjusting per internal and external feedback:** 258 | 259 | As users use the beta, issues will be opened for bugs and suggestions. Appropriate adjustments to the library should be made with a focus on doing what users expect while minimizing technical debt. For that purpose, breaking changes to the new API can still be introduced and documentation should be updated accordingly at the moment of publishing a new beta. 260 | 261 | ### Stable (`x.x.x`) 262 | 263 | > Once the beta phase has arrived to maturity (users seem to be happy with it, all issues and concerns have been addressed, etc.), the project enters the stable phase. 264 | > 265 | > The goal of the stable phase is to publish the new project version and to advocate it as Prismic's latest standard. During this "living" phase of the project bug fixes and new features will be added. If the need for breaking or large changes arises, the project will enter the pre-alpha phase and begin a new cycle. 266 | 267 | During the stable phase, the following will happen: 268 | 269 | **Publishing public stable versions and related documentation:** 270 | 271 | The first stable version should be published along the related documentation. This release should be announced and shared to users extensively in order to get them up to Prismic latest standard. Subsequent stable versions can be published as often as needed but a particular attention should be paid toward testing and avoiding regressions. 272 | 273 | **Implementing new features:** 274 | 275 | New features can be implemented during the stable phase following user suggestions and new use cases discovered. To be published, new features should be extensively tested. Ideally, documentation should be updated at the time of publishing, however a delay is tolerated here as it requires coordination with the Prismic Education team. 276 | 277 | **Adding new examples:** 278 | 279 | While examples can be added at any time, it's certainly during the stable phase that most of them will be added. Examples should be added whenever it feels relevant for a use case to be pictured with a recommended recipe, allowing for later shares of said examples. 280 | 281 | ## Project Structure 282 | 283 | > Prismic open-source projects have been structured around standards maintainers brought from their different background and agreed upon on. They are meant to implement the same sensible defaults allowing for a coherent open-source ecosystem. 284 | > 285 | > Any changes to this structure are welcome but they should be first discussed on our [TypeScript template][template-issue]. Common sense still applies on a per-project basis if one requires some specific changes. 286 | 287 | Project is structured as follows (alphabetically, folders first): 288 | 289 | ### 📁  `.github` 290 | 291 | This folder is used to configure the project's GitHub repository. It contains: 292 | 293 | **Issue templates (`ISSUE_TEMPLATE/*`)** 294 | 295 | Those are used to standardize the way issues are created on the repository and to help with their triage by making sure all needed information is provided. Issue templates are also used to redirect users to our [community forum][community-forum] when relevant. 296 | 297 | **Pull request templates (`PULL_REQUEST_TEMPLATE.md`)** 298 | 299 | This one is used to standardize the way pull requests are created on the repository and to help with their triage by making sure all needed information is provided. 300 | 301 | **CI configuration (`.github/workflows/ci.yml`)** 302 | 303 | Our CI workflow is configured to run against all commits and pull requests directed toward the `master` branch. It makes sure the project builds and passes all tests configured on it (lint, unit, e2e, etc.) Coverage and bundle size are also collected by this workflow. 304 | 305 | ### 📁  `dist` 306 | 307 | This folder is not versioned. It contains the built artifacts of the project after a successful build. 308 | 309 | ### 📁  `examples` 310 | 311 | This folder contains examples of how to use the project. Examples are meant to be written over time as new use cases are discovered. 312 | 313 | ### 📁  `playground` 314 | 315 | This folder might not be available in this project. If it is, it is meant to contain a playground for developers to try the project during the development process. 316 | 317 | Scripts such as `playground:dev` or `playground:build` might be available inside the project [package.json](#-packagejson) to interact with it easily. 318 | 319 | ### 📁  `src` 320 | 321 | This folder contains the source code of the project written in TypeScript. The `index.ts` file inside it should only contain exports made available by the project. It should not contain any logic. 322 | 323 | ### 📁  `test` 324 | 325 | This folder contains tests of the project written in TypeScript. It may contain the following subdirectory: 326 | 327 | **Fixtures (`__fixtures__`)** 328 | 329 | This folder contains [fixtures](https://en.wikipedia.org/wiki/Test_fixture) used to test the project. 330 | 331 | **Test Utils (`__testutils__`)** 332 | 333 | This folder contains utility functions used to test the project. 334 | 335 | **Snapshots (`snapshots`)** 336 | 337 | This folder contains snapshots generated by the test framework when using snapshot testing strategies. It should not be altered manually. 338 | 339 | ### 📄  `.editorconfig`, `.eslintrc.cjs`, `.prettierrc`, `.size-limit.json`, `.versionrc`, `ava.config.js`, `siroc.config.ts`, `tsconfig.json` 340 | 341 | These files contain configuration for their eponymous tools: 342 | 343 | - [EditorConfig][editor-config]; 344 | - [ESLint][eslint]; 345 | - [Prettier][prettier]; 346 | - [Size Limit][size-limit]; 347 | - [Standard Version][standard-version]; 348 | - [AVA][ava]; 349 | - [`siroc`][siroc]; 350 | - [TypeScript][typescript]. 351 | 352 | Any change to those files are welcome but they should be first discussed on our [TypeScript template][template-issue]. Common sense still applies if the project requires some specific changes. 353 | 354 | ### 📄  `.eslintignore`, `.gitignore`, `.prettierignore` 355 | 356 | These files contain ignore configuration for their eponymous tools. Ignore configuration should be based on the one available from `.gitignore` and extended from it. 357 | 358 | ### 📄  `.gitattributes` 359 | 360 | This file contains [attributes](https://git-scm.com/docs/gitattributes) used by Git to deal with the project's files. Our configuration makes sure all files use correct line endings and that lock files aren't subject to conflicts. 361 | 362 | ### 📄  `CHANGELOG.md` 363 | 364 | This file is automatically generated by [Standard Version](https://github.com/conventional-changelog/standard-version) according to commit messages following the [Conventional Commits specification][conventional-commits] whenever a release is made. 365 | 366 | ### 📄  `CONTRIBUTING.md`, `README.md` 367 | 368 | These files contain project's related information and developers (maintainers) documentation. 369 | 370 | ### 📄  `LICENSE` 371 | 372 | This file contains a copy of the project's Apache 2.0 license we use on this project. The Apache 2.0 license has a few more restrictions over the MIT one. Notably (not legal advice), any change by a third party to Apache 2.0 licensed code is required to be stated by the third party. Same applies for changes to the project name by a third party (still not legal advice). For full details refer to the [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0) license text itself. 373 | 374 | ### 📄  `package-lock.json` 375 | 376 | This file is the lock file generated by [npm][npm] to represent the resolved dependencies used by the project. We use npm over [Yarn][yarn] to manage dependencies and only this lock file should be versioned (`yarn.lock` is even ignored to prevent mistakes). 377 | 378 | ### 📄  `package.json` 379 | 380 | The project's package definition file. 381 | 382 | **Scripts (`scripts`)** 383 | 384 | - `build`: Builds the project; 385 | - `dev`: Builds the project with watch mode enabled; 386 | - `playground:*`: Any command related to the project [playground](#-playground) if any; 387 | - `format`: Runs Prettier on the project; 388 | - `prepare`: npm life cycle script to make sure the project is built before any npm related command (`publish`, `install`, etc.); 389 | - `release`: creates and publishes a new release of the package, version is determined after commit messages following the [Conventional Commits specification][conventional-commits]; 390 | - `release:dry`: dry-run of the `release` script; 391 | - `release:alpha`: creates and publishes a new alpha release of the package; 392 | - `release:alpha:dry`: dry-run of the `release:alpha` script; 393 | - `lint`: Runs ESLint on the project; 394 | - `unit`: Runs AVA on the project; 395 | - `size`: Runs Size Limit on the project; 396 | - `test`: Runs the `lint`, `unit`, `build`, and `size` scripts. 397 | 398 | **Minimum Node version supported (`engines.node`)** 399 | 400 | The minimum Node version supported by the project is stated under the `engines` object. We aim at supporting the oldest Long Term Support (LTS) version of Node that has still not reached End Of Life (EOL): [nodejs.org/en/about/releases](https://nodejs.org/en/about/releases) 401 | 402 | 403 | 404 | [prismic-docs]: https://prismic.io/docs 405 | [community-forum]: https://community.prismic.io 406 | [conventional-commits]: https://conventionalcommits.org/en/v1.0.0 407 | [npm]: https://www.npmjs.com 408 | [yarn]: https://yarnpkg.com 409 | [editor-config]: https://editorconfig.org 410 | [eslint]: https://eslint.org 411 | [prettier]: https://prettier.io 412 | [size-limit]: https://github.com/ai/size-limit 413 | [standard-version]: https://github.com/conventional-changelog/standard-version 414 | [ava]: https://github.com/avajs/ava 415 | [siroc]: https://github.com/unjs/siroc 416 | [typescript]: https://www.typescriptlang.org 417 | [template]: https://github.com/prismicio/prismic-typescript-template 418 | [template-issue]: https://github.com/prismicio/prismic-typescript-template/issues/new/choose 419 | [changelog]: ./CHANGELOG.md 420 | [forum-question]: https://community.prismic.io 421 | [repo-issue]: https://github.com/github_org_slash_github_repo/issues/new/choose 422 | [repo-pull-requests]: https://github.com/github_org_slash_github_repo/pulls 423 | --------------------------------------------------------------------------------