Merge pull request #133 from Kentico/feature/preview-create

Feature/preview support

Author: Simply007

.vscode/launch.json

@@ -28,7 +28,8 @@
       "name": "Develop site",
       "program": "${workspaceFolder}/node_modules/gatsby/dist/bin/gatsby",
       "args": [
-        "develop"
+        "develop",
+        "--verbose"
       ],
       "stopOnEntry": false,
       "cwd": "${workspaceFolder}/site",
@@ -39,11 +40,15 @@
       ],
       "restart": true,
       "internalConsoleOptions": "neverOpen",
-      "env": { 
+      "env": {
         "NODE_ENV": "development",
+        "ENABLE_GATSBY_REFRESH_ENDPOINT": "true",
         // "DEBUG": "gatsby:*" 
       },
       "console": "integratedTerminal",
+      "skipFiles": [
+        "<node_internals>/**/*.js"
+      ]
     }
   ]
 }

README.md

@@ -79,7 +79,7 @@ To lint all of the packages as well as a development site, you could use one com
 
 As a publishing framework, there is a [Lerna](https://github.com/lerna/lerna) framework set up. This package is using [Fixed/Locked mode](https://github.com/lerna/lerna#fixedlocked-mode-default). All minor and major changes should publish all packages, in case of patch version, it is up to developer decision.
 
-### How to publish new (vNext) version 
+### How to publish new (vNext) version
 
 If you have the rights to publish packages, just use [`lerna publish`](https://github.com/lerna/lerna/tree/master/commands/publish#readme) with appropriate tags and then specify the version when prompted. All the changes made by lerna are automatically committed.
 

lerna.json

@@ -4,5 +4,5 @@
     "!packages/site",
     "packages/*"
   ],
-  "version": "6.0.0-vnext.1"
+  "version": "6.0.0-vnext.4"
 }

package.json

@@ -23,14 +23,14 @@
     "prepublishOnly": "yarn build",
     "build:site": "yarn workspace @kentico/gatsby-starter-kontent-hello-world build",
     "develop:site": "yarn workspace @kentico/gatsby-starter-kontent-hello-world develop",
-    "develop:site:playground": "cross-env  GATSBY_GRAPHQL_IDE=playground yarn develop:site",
+    "develop:site:playground": "cross-env GATSBY_GRAPHQL_IDE=playground yarn develop:site",
     "watch:source": "yarn workspace @kentico/gatsby-source-kontent watch",
     "watch:components": "yarn workspace @kentico/gatsby-kontent-components watch",
     "build:source": "yarn workspace @kentico/gatsby-source-kontent build",
     "test:source": "yarn workspace @kentico/gatsby-source-kontent test",
     "set:version": "export LERNA_VERSION=\"$(node -e \"require('./lerna.json').version\")\"",
-    "publish:vnext-alpha": "lerna publish --no-git-tag-version --force-publish --dist-tag=vnext-alpha",
-    "publish:vnext-beta": "lerna publish --no-git-tag-version --force-publish --dist-tag=vnext-beta",
+    "publish:vnext-alpha": "lerna publish --force-publish --tag-version-prefix='' --dist-tag=vnext-alpha",
+    "publish:vnext-beta": "lerna publish --force-publish --tag-version-prefix='' --dist-tag=vnext-beta",
     "publish:vnext": "lerna publish --force-publish --tag-version-prefix='' --dist-tag=vnext"
   },
   "devDependencies": {

packages/gatsby-kontent-components/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kentico/gatsby-kontent-components",
   "description": "Source plugin providing Kentico Kontent data from REST Delivery API",
-  "version": "6.0.0-vnext.1",
+  "version": "6.0.0-vnext.4",
   "main": "dist/index.js",
   "license": "MIT",
   "author": {

packages/gatsby-source-kontent/README.md

@@ -41,8 +41,11 @@ This plugin does not need to use `yarn`, if want to use it in you project, see [
 - `languageCodenames`\* - \<`string[]`\> array of language codenames that defines [what languages a configured for the project](https://docs.kontent.ai/tutorials/develop-apps/get-content/getting-localized-content?tech=javascript#section-project-languages) - the first one is considered as the **default one**. Initial "Getting started" project has configured just one language `default`.
 - `includeTaxonomies` - \<`boolean`\> include [taxonomies](#Querying-Kontent-Taxonomies) to GraphQL model. Turned off by default.
 - `includeTypes` - \<`boolean`\> include [types](#Querying-Kontent-Types) to GraphQL model. Turned off by default.
-- `authorizationKey` - \<`string`\> For preview/secured API key - depends on `usePreviewUrl` config.
+- `authorizationKey` - \<`string`\> For preview/secured API key - depends on `usePreviewUrl` config. Consider using [dotenv](https://www.npmjs.com/package/dotenv) package for storing keys securely in environment variables.
 - `usePreviewUrl` - \<`boolean`\> when `true`, "`preview-deliver.kontent.ai`" used as [primary domain for data source](https://docs.kontent.ai/reference/delivery-api#section/Production-vs.-Preview). Turned off by default.
+- `proxy`:
+  - `deliveryDomain` - \<`string`\> Base url used for all requests. Defaults to `deliver.kontent.ai`.
+  - `previewDeliveryDomain` - \<`string`\> Base url used for preview requests. Defaults to `preview-deliver.kontent.ai`.
 - `includeRawContent` - \<`boolean`\> allows to include `internal.content` property as a part fo the GraphQL model. Turned off by default.
 
   \* required property
@@ -72,8 +75,12 @@ module.exports = {
         includeTaxonomies: true, // opt-out by default
         includeTypes: true, // opt-out by default
         usePreviewUrl: true, // false by default
-        authorizationKey: '<API KEY>', // For preview/secured API key - depends on usePreviewUrl setting
+        authorizationKey: '<API KEY>', // for preview/secured API key - depends on `usePreviewUrl` setting - consider using environment variables to store the key securely
         includeRawContent: true, // opt-out by default - include `internal.content` property in the gatsby nodes
+        proxy: {
+          deliveryDomain: 'custom.delivery.kontent.my-proxy.com',
+          previewDeliveryDomain: "custom.preview.delivery.kontent.my-proxy.com"
+        }
       },
     },
     /// ...
@@ -430,6 +437,12 @@ query Taxonomies {
 }
 ```
 
+## How to integrate with Gatsby Cloud
+
+If you choose to maintain you Gatsby site on [Gatsby Cloud](https://gatsbyjs.com), use will need to register two webhooks from Kentico Kontent Kontent to Gatsby Cloud. Follow [the tutorial](./docs/GATSBY-CLOUD.md) for more information. All webhook notification that are not mentioned in the tutorial will be ignored by the plugin.
+
+Please note that change in taxonomies or content types require manual rebuild of the site, because these structural data affects GraphQL schema.
+
 ## How to run tests
 
 The package is using [Jest](http://jest.org/) framework for testing.

packages/gatsby-source-kontent/docs/GATSBY-CLOUD.md

@@ -0,0 +1,156 @@
+# Getting started with Gatsby Cloud and Kontent
+
+Learn how to connect Gatsby Cloud with Kentico Kontent based Gatsby site.
+
+In this tutorial you will discover how to easily integrate site sourced by Kentico Kontent with Gatsby Cloud.
+
+You will
+
+* Create a website using data from Kentico Kontent.
+* Store its source Code on GitHub.
+* Register this Github repository in Gatsby Cloud.
+* Configure Kentico Kontent webhooks to notify Gatsby Cloud about the content changes on preview environment as well as on production.
+* Configure preview URLs in Kentico Kontent.
+
+## What are Gatsby Cloud and Kontent, and why use them together
+
+[Kontent](https://kontent.ai) is a headless CMS that content editors can use to edit and publish content. It is a Content-as-a-Service solution that gives enterprises control over their entire content lifecycle in a single unified environment. Gatsby Cloud allows you to integrate your site with Kontent in order to run performant builds and preview content changes made in the CMS before publishing.
+
+## Setting up a Kontent and Gatsby site
+
+First, you’ll need a Gatsby site with a [gatsby-source-kontent](https://www.gatsbyjs.org/packages/@kentico/gatsby-source-kontent) source plugin to pull data from Kontent. If you haven’t set that up yet, you can quickly create a new project by using the [gatsby-starter-kontent-lumen](https://github.com/Kentico/gatsby-starter-kontent-lumen) repository. ~~To achieve it, see the [Getting started](https://github.com/kentico/gatsby-starter-kontent-lumen#getting-started) tutorial.~~
+
+> Note that source plugin version supporting Gatsby Cloud is in beta phase (internally called [`vNext`](https://github.com/Kentico/gatsby-source-kontent/tree/vNext/packages/gatsby-source-kontent#readme) version), so use the link to the development branch to [Getting started](https://github.com/Simply007/gatsby-starter-kontent-lumen/tree/vNext#getting-started) section. to be able to spin up project supporting Gatsby Cloud.
+
+## Signing in to Gatsby Cloud
+
+[Access Gatsby Cloud](https://gatsbyjs.com/dashboard/sites/create) and select **Sign in with GitHub**. You’ll be asked to authorize the Gatsby Cloud app with your GitHub account. If you need to request access to one or more repositories, you can click *request access* now or later when creating an instance.
+
+Once signed in, configuring Gatsby Cloud with Kontent requires several steps that are walked through below.
+
+### Creating an instance
+
+Start by [registering you GitHub repository](https://gatsbyjs.com/dashboard/sites/create).
+
+Use the **I already have a Gatsby site** flow to manually integrate your site.
+
+![Add my own site](./assets/import-flow-start.png)
+
+### Select an organization & repository
+
+Pick your Gatsby site from the list of GitHub repositories.
+
+If you don’t see your site, it might be because it belongs to a GitHub organization rather than your personal account. You can connect a new GitHub Organization.
+
+*Note: Repositories must contain one Gatsby project configured at their root to be enabled. Gatsby Cloud works best with Gatsby version 2.20.36 and higher.*
+
+You’ll need to select a branch and then indicate the publish directory where the `gatsby-config.js` lives. If you leave the field blank, it defaults to the root of the site.
+
+![Gatsby Cloud Add an instance page](./assets/select-repo.png)
+
+Once the branch and publish directory are correct, select **Next**.
+
+### Create the instance
+
+Click **Skip this step** to configure Kontent manually.
+
+![Integration Step - automatic or manual](./assets/integration-step.png)
+
+*Gatsby Cloud will automatically try and detect environment variables necessary in your `gatsby-config.js`. However — consider adding any additional variables that the automatic detection may have missed. See [Setting up Environment Variables](#setting-up-environment-variables) for more info. You'll be able to add, delete, or update these later on in your Site Settings.*
+
+### Setting up Environment Variables
+
+An environment variable references a value that can affect how running processes will behave in a specific environment, such as staging and production environments. You must save your environment variables in Gatsby Cloud to authorize your instance to pull source data from Kontent.
+
+First, open your Kontent project and go to **Project settings** > **API Keys**. 
+On the API keys screen, copy the values for **Project ID** and **Preview API key** (Primary or Secondary).
+
+![Kontent API keys section](./assets/kontent-api-keys.png)
+
+Then go to **Project settings** > **Localization** to get the codenames of your project languages.
+
+![Kontent Localization configuration section](./assets/kontent-localization.png)
+
+The language codenames used in the [`gatsby-starter-kontent-lumen`](https://github.com/Kentico/gatsby-starter-kontent-lumen) sample app are `en-US,cs-CZ`.
+
+Value | Environment Variable Name
+------------ | -------------
+<YOUR_PROJECT_ID> | KONTENT_PROJECT_ID
+<YOUR_PREVIEW_API_KEY> | KONTENT_PREVIEW_KEY
+<YOUR_LANGUAGE1,YOUR_LANGUAGE2> | KONTENT_LANGUAGE_CODENAMES
+
+You will want to set `KONTENT_PREVIEW_ENABLED` to `true` for Preview and `false` for Builds.
+
+![Environment variables](./assets/environment-variables.png)
+
+Once you’ve entered your variables, click **Save** and then **Create site**.
+
+Go to the *Preview* tab and wait for the preview instance to be created.
+
+## Webhooks: Configuring your Gatsby site to be updated with content changes
+
+To connect Kontent with your Gatsby Cloud instance, you’ll need to [configure a webhook](https://docs.kontent.ai/tutorials/develop-apps/integrate/webhooks#a-creating-a-webhook) in Kontent so that content changes can be pushed to Gatsby Cloud.
+
+You’ll add two webhooks in Kontent: one for Gatsby Preview and another for Gatsby Builds.
+
+### Adding a Preview Webhook
+
+Navigate to your Gatsby Cloud instance and click **Site Settings**. Copy the *Preview Webhook* on this page.
+
+![Copying the Preview webhook URL](./assets/webhook-preview.png)
+
+In your Kentico Kontent project, go to **Project settings** > **Webhooks** and click **Create new webhook**.
+
+![Kontent webhooks menu](./assets/kontent-webhooks.png)
+
+Name the webhook and paste the *Preview webhook* into the URL address field.
+
+> Following webhook triggers are currently available via [API](https://docs.kontent.ai/reference/management-api-v2#operation/add-a-webhook) (use `preview_delivery_api_content_changes` as trigers section and `uspert` + `archive` as operations). The UI and documentation is about to be released in the next iteration. (The UI is currently available on QA environment)
+
+In the webhook configuration, select the *Create or Update* and *Delete* triggers under DELIVERY PREVIEW API TRIGGERS.
+
+![Kontent preview webhook configuration](./assets/preview-webhook-configuration.png)
+
+Click **Save**.
+
+Your Preview webhook is now ready! When you change your content in Kontent, your Gatsby Preview will update!
+
+### Adding a Build Webhook
+
+Navigate to your Gatsby Cloud instance and click **Site Settings**. Copy the Build Webhook on this page.
+
+![Copying the Build webhook URL](./assets/webhook-builds.png)
+
+In Kentico Kontent, go to **Project settings** > **Webhooks** and click **Create new webhook**.
+
+![Kontent webhooks menu with one webhook](./assets/kontent-webhooks-with-webhook.png)
+
+Name the webhook and paste the *Build webhook* in the URL address field.
+
+In the webhook configuration, select the *Publish* and *Unpublish* triggers under DELIVERY API TRIGGERS.
+
+![Kontent build webhook configuration](./assets/build-webhook-configuration.png)
+
+Click **Save**.
+
+Your Build webhook is now ready! When you publish/unpublish content in Kontent, your Gatsby Build will update!
+
+## Setting the Gatsby Preview Domain for Kontent
+
+To open the Gatsby Cloud preview right from Kentico Kontent, you need to [configure preview URLs](https://docs.kontent.ai/tutorials/develop-apps/build-strong-foundation/set-up-preview#a-set-up-content-preview-in-your-project) for your content. The following instructions assume you're using the [`gatsby-starter-kontent-lumen`](https://github.com/Kentico/gatsby-starter-kontent-lumen) sample app.
+
+Navigate to your Gatsby Cloud instance and click **Preview**. Copy the preview URL.
+
+![Gatsby cloud preview URL](./assets/gatsby-cloud-preview-url.png)
+
+In Kentico Kontent, go to **Project settings** > **Preview URLs** and provide the URLs according to your routes configuration.
+
+![Preview URLs configuration](./assets/preview-urls.png)
+
+Now you can open the content preview right from Kentico Kontent UI!
+
+![Preview button showcase in Kontent](./assets/preview-showcase.png)
+
+## Wrapping Up
+
+At this point, you have a Kontent instance configured to best support Gatsby Cloud. Edit content, click the Preview button, and watch it appear live in Gatsby Cloud!

packages/gatsby-source-kontent/docs/UPGRADE.md

@@ -64,6 +64,13 @@ If you want to extend the model with `contentItems` feel free to do so using [Co
 All nodes had a `usedByContentItems` property that reflects the other nodes in which the given node is used as linked content in Linked items or Rich text elements.
 Now it is possible to substitute this property by using [Linked from relationship](../../../site/README.md#Linked-from-relationship), it is just required to specify an element to gather the links from.
 
+### Different Item Node IDs
+
+In previous version there was a Node ID generated from item `system.codename`, `preferred_language`, and some prefix.
+Since the `system.codename` is changeable for content item, now as an input for node ID generation function `system.id` is used.
+
+If you are using hard-coded Node ID in your queries to get/filter specific Kontent item node(s), you need to make the adjustments - IDs will be different for version 6.
+
 ## From `4.x.x` to `5.x.x`
 
 This upgrade is necessary to fix the [colliding identifiers](https://github.com/Kentico/gatsby-source-kontent/issues/110) issue.