@prezly/theme-kit-nextjs 1.1.0 → 1.1.4

package/README.md

@@ -1,6 +1,11 @@
 # NextJS Prezly Theme Kit
 
-This library is a collection of data-fetching functions, hooks and utility functions to abstract some of the under-the-hood logic used by Prezly newsrooms and help developers create themes much faster with little boilerplate required.
+![Version](https://img.shields.io/npm/v/@prezly/theme-kit-nextjs)
+![License](https://img.shields.io/npm/l/@prezly/theme-kit-nextjs)
+
+This library is a collection of data-fetching functions, hooks and utility functions to abstract some of the under-the-hood logic used by Prezly newsrooms and help developers create themes with [Next.JS] much faster with little boilerplate required.
+
+The package is built with [Typescript] on top of [Prezly SDK].
 
 ## Adding the library to your NextJS theme
 
@@ -12,8 +17,8 @@ npm install --save @prezly/theme-kit-nextjs
 
 #### peerDependencies
 
-This library is intended to be used with NextJS applications, so it requires `next`, `react` and `react-dom` to work. These should already be installed if you have an existing NextJS app. 
-If you're starting from scratch, use [`create-next-app`](https://nextjs.org/docs/api-reference/create-next-app) to quick-start the project.
+This library is intended to be used with [Next.JS] applications, so it requires `next`, `react` and `react-dom` to work. These should already be installed if you have an existing NextJS app. 
+If you're starting from scratch, use [create-next-app] to quick-start the project.
 
 To keep things fresh, we require at least NextJS 12 and React 17.
 
@@ -23,6 +28,193 @@ npm install --save next react react-dom
 npm install --save-dev @types/react @types/react-dom
 ```
 
+### .env
+
+Prezly themes use two ways of getting base environment variables:
+- Getting variables straight from `.env` file
+- Extracting variables from HTTP headers (when hosted on the Prezly infrastructure)
+
+For local development, and for self-hosted themes, you can only use the former option. Add these two variables to your `.env` file:
+```
+PREZLY_ACCESS_TOKEN=your access token
+PREZLY_NEWSROOM_UUID=your newsroom UUID
+```
+
+If you don't have these credentials, you can use one of our [testing newsrooms credentials](https://github.com/prezly/theme-nextjs-starter#testingtoken).
+
+### next.config.js
+
+In a base setup, you don't have to make any changes to your config.
+Depending on your use-case, you might need to make some additions to your base config.
+
+#### Using next/image to display images served from Prezly
+
+We provide `@prezly/uploadcare-image` package to conviniently display images inside Prezly content, and this is the recommended way to display images in your theme.
+However, if you need to use the default `next/image` component, you will need to add our CDN url to image domains settings:
+```js
+module.exports = {
+    /* ...your next config... */
+    images: {
+        domains: ['cdn.uc.assets.prezly.com'],
+    },
+};
+```
+
+#### Multi-language support
+
+If you want to support multi-language in your theme, you'll need to make additional changes to the file:
+
+```js
+const { DUMMY_DEFAULT_LOCALE } = require('@prezly/theme-kit-nextjs');
+const locales = require('@prezly/theme-kit-nextjs/build/intl/localeConfig');
+
+module.exports = {
+    /* ...your next config... */
+    
+    i18n: {
+        // These are all the locales you want to support in
+        // your application
+        locales: [...locales, DUMMY_DEFAULT_LOCALE],
+        // This is the default locale you want to be used when visiting
+        // a non-locale prefixed path e.g. `/media`
+        // We use Pseudo locale used for localization testing, to reliably determine if we need to fallback to the default newsroom language
+        defaultLocale: DUMMY_DEFAULT_LOCALE,
+        // Default locale detection is disabled, since the locales would be determined by Prezly API
+        localeDetection: false,
+    },
+};
+```
+
+### pages/_app.tsx
+
+In order to provide all the necessary data to the entire application, we provde the `NewsroomContextProvider` component, which accepts props provided by our data-fetching methods (which you'll need to call in each page's `getServerSideProps` method).
+
+```ts
+import { BasePageProps, NewsroomContextProvider } from '@prezly/theme-kit-nextjs';
+import { AppProps } from 'next/app';
+
+type AnyPageProps = Record<string, any>;
+
+function App({ Component, pageProps }: AppProps<AnyPageProps>) {
+    const {
+        categories,
+        contacts,
+        newsroom,
+        companyInformation,
+        languages,
+        localeCode,
+        themePreset,
+        algoliaSettings,
+        selectedCategory,
+        selectedStory,
+        hasError,
+        ...customPageProps
+    } = pageProps as BasePageProps & AnyPageProps;
+
+    return (
+        <NewsroomContextProvider
+            categories={categories}
+            contacts={contacts}
+            newsroom={newsroom}
+            companyInformation={companyInformation}
+            languages={languages}
+            localeCode={localeCode}
+            themePreset={themePreset}
+            selectedCategory={selectedCategory}
+            selectedStory={selectedStory}
+            algoliaSettings={algoliaSettings}
+            hasError={hasError}
+        >
+            {/* eslint-disable-next-line react/jsx-props-no-spreading */}
+            <Component {...customPageProps} />
+        </NewsroomContextProvider>
+    );
+}
+
+export default App;
+```
+
+### Page files (Server-side rendering)
+
+Every page requires a bit of boilerplate code to set up.
+
+```ts
+import { BasePageProps, getBasePageProps, processRequest } from '@prezly/theme-kit-nextjs';
+import { GetServerSideProps } from 'next';
+import type { FunctionComponent } from 'react';
+
+interface Props extends BasePageProps {
+    /* Additional props for this page */
+}
+
+const Page: FunctionComponent<Props> = () => <>{/* Your display components */}</>;
+
+export const getServerSideProps: GetServerSideProps<Props> = async (context) => {
+    const { api, basePageProps } = await getBasePageProps(context);
+
+    /* Your logic to get additional props for this page  */
+
+    // '/' is the canonical URL of your page without locale prefix
+    return processRequest(context, basePageProps, '/', {
+        /* Additional props for this page */
+    });
+};
+
+export default Page;
+```
+
+
+#### Here's a breakdown of what's happening:
+
+**Prop types**
+```ts
+interface Props extends BasePageProps {
+    /* Additional props for this page */
+}
+```
+Every page props should extend `BasePageProps` type, since they are required for `NewsroomContextProvider` added previously.
+These props contain data that would be required to display common components like navigation, language picker, boilerplate, etc.
+
+**Page display component**
+```ts
+const Page: FunctionComponent<Props> = () => <>{/* Your display components */}</>;
+```
+Since all of the common data is loaded into the `NewsroomContextProvider`, you don't need to handle any of those in your display components. So the Page component should just handle rendering the provided data.
+
+**Data fetching**
+```ts
+const { api, basePageProps } = await getBasePageProps(context);
+```
+This function fetches all the required base props and exposes the `PrezlyApi` instance, which you can use to fetch additional content like stories or categories.
+
+```ts
+// '/' is the canonical URL of your page without locale prefix
+return processRequest(context, basePageProps, '/', {
+    /* Additional props for this page */
+});
+```
+This function returns the combined base props and your additional props, with some extra logic in between to handle locale URLs.
+
+The third argument is required to properly handle locale redirects. It should contain the URL for the current page without locale prefixes (like `/`, `/media`, `/category/${category.slug}`.
+
+----
+
+## What's next
+
+This kit is just a collection of building blocks, so it doesn't really force any page structure or guidelines on how to render the content.
+You can learn more on how this kit can be used by checking the code of Prezly's themes:
+- [Theme Starter](https://github.com/prezly/theme-nextjs-starter) - this is a bare-bones application created to demonstrate how to display the fetched content and recommended page structure
+- [Bea Theme](https://github.com/prezly/theme-nextjs-bea) - this is our new fully-fledged theme available to all Prezly customers. It has lots of stuff on top, both in styling and in data logic.
+
+You can also learn more about Prezly API by checking out typings in [Prezly SDK] package, and referring to the [Prezly API Docs]
+
 ----
 
 Brought to you by [Prezly](https://www.prezly.com/?utm_source=github&utm_campaign=@prezly/theme-kit-nextjs).
+
+[create-next-app]: https://nextjs.org/docs/api-reference/create-next-app
+[Next.JS]: https://nextjs.org
+[Prezly SDK]: https://www.npmjs.com/package/@prezly/sdk
+[Prezly API Docs]: https://developers.prezly.com/docs/api
+[Typescript]: https://www.typescriptlang.org
+[Prezly Content React Renderer]: https://www.npmjs.com/package/@prezly/content-renderer-react-js

package/build/adapter-nextjs/getBasePageProps.js

@@ -1,15 +1,65 @@
 "use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
+    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (_) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getBasePageProps = void 0;
-const data_fetching_1 = require("../data-fetching");
-async function getBasePageProps(context, options = {}) {
-    const { req: request, locale } = context;
-    const api = (0, data_fetching_1.getPrezlyApi)(request);
-    const basePageProps = await api.getBasePageProps(request, locale);
-    if (options.loadHomepageContacts) {
-        basePageProps.contacts = await api.getNewsroomContacts();
-    }
-    return { api, basePageProps };
+var data_fetching_1 = require("../data-fetching");
+function getBasePageProps(context, options) {
+    if (options === void 0) { options = {}; }
+    return __awaiter(this, void 0, void 0, function () {
+        var request, locale, api, basePageProps, _a;
+        return __generator(this, function (_b) {
+            switch (_b.label) {
+                case 0:
+                    request = context.req, locale = context.locale;
+                    api = (0, data_fetching_1.getPrezlyApi)(request);
+                    return [4 /*yield*/, api.getBasePageProps(request, locale)];
+                case 1:
+                    basePageProps = _b.sent();
+                    if (!options.loadHomepageContacts) return [3 /*break*/, 3];
+                    _a = basePageProps;
+                    return [4 /*yield*/, api.getNewsroomContacts()];
+                case 2:
+                    _a.contacts = _b.sent();
+                    _b.label = 3;
+                case 3: return [2 /*return*/, { api: api, basePageProps: basePageProps }];
+            }
+        });
+    });
 }
 exports.getBasePageProps = getBasePageProps;
 //# sourceMappingURL=getBasePageProps.js.map

package/build/adapter-nextjs/getBasePageProps.js.map

@@ -1 +1 @@
-{"version":3,"file":"getBasePageProps.js","sourceRoot":"","sources":["../../src/adapter-nextjs/getBasePageProps.ts"],"names":[],"mappings":";;;AAEA,oDAAgD;AAMzC,KAAK,UAAU,gBAAgB,CAClC,OAAkC,EAClC,UAAgC,EAAE;IAElC,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IAEzC,MAAM,GAAG,GAAG,IAAA,4BAAY,EAAC,OAAO,CAAC,CAAC;IAClC,MAAM,aAAa,GAAG,MAAM,GAAG,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAElE,IAAI,OAAO,CAAC,oBAAoB,EAAE;QAC9B,aAAa,CAAC,QAAQ,GAAG,MAAM,GAAG,CAAC,mBAAmB,EAAE,CAAC;KAC5D;IAED,OAAO,EAAE,GAAG,EAAE,aAAa,EAAE,CAAC;AAClC,CAAC;AAdD,4CAcC"}
+{"version":3,"file":"getBasePageProps.js","sourceRoot":"","sources":["../../src/adapter-nextjs/getBasePageProps.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEA,kDAAgD;AAMhD,SAAsB,gBAAgB,CAClC,OAAkC,EAClC,OAAkC;IAAlC,wBAAA,EAAA,YAAkC;;;;;;oBAErB,OAAO,GAAa,OAAO,IAApB,EAAE,MAAM,GAAK,OAAO,OAAZ,CAAa;oBAEnC,GAAG,GAAG,IAAA,4BAAY,EAAC,OAAO,CAAC,CAAC;oBACZ,qBAAM,GAAG,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAM,CAAC,EAAA;;oBAA3D,aAAa,GAAG,SAA2C;yBAE7D,OAAO,CAAC,oBAAoB,EAA5B,wBAA4B;oBAC5B,KAAA,aAAa,CAAA;oBAAY,qBAAM,GAAG,CAAC,mBAAmB,EAAE,EAAA;;oBAAxD,GAAc,QAAQ,GAAG,SAA+B,CAAC;;wBAG7D,sBAAO,EAAE,GAAG,KAAA,EAAE,aAAa,eAAA,EAAE,EAAC;;;;CACjC;AAdD,4CAcC"}

package/build/adapter-nextjs/processRequest.js

@@ -1,23 +1,31 @@
 "use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.processRequest = void 0;
-const intl_1 = require("../intl");
+var intl_1 = require("../intl");
 function processRequest(context, basePageProps, canonicalUrl, customProps) {
-    const { locale, query } = context;
+    var locale = context.locale, query = context.query;
     if (!basePageProps.localeResolved) {
         return { notFound: true };
     }
     if (canonicalUrl) {
-        const redirect = (0, intl_1.getRedirectToCanonicalLocale)(basePageProps, locale, canonicalUrl, query);
+        var redirect = (0, intl_1.getRedirectToCanonicalLocale)(basePageProps, locale, canonicalUrl, query);
         if (redirect) {
-            return { redirect };
+            return { redirect: redirect };
         }
     }
     return {
-        props: {
-            ...basePageProps,
-            ...customProps,
-        },
+        props: __assign(__assign({}, basePageProps), customProps),
     };
 }
 exports.processRequest = processRequest;

package/build/adapter-nextjs/processRequest.js.map

@@ -1 +1 @@
-{"version":3,"file":"processRequest.js","sourceRoot":"","sources":["../../src/adapter-nextjs/processRequest.ts"],"names":[],"mappings":";;;AAEA,kCAAuD;AAGvD,SAAgB,cAAc,CAC1B,OAAkC,EAClC,aAA4B,EAC5B,YAAqB,EACrB,WAA8C;IAE9C,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC;IAElC,IAAI,CAAC,aAAa,CAAC,cAAc,EAAE;QAC/B,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;KAC7B;IAED,IAAI,YAAY,EAAE;QACd,MAAM,QAAQ,GAAG,IAAA,mCAA4B,EAAC,aAAa,EAAE,MAAM,EAAE,YAAY,EAAE,KAAK,CAAC,CAAC;QAC1F,IAAI,QAAQ,EAAE;YACV,OAAO,EAAE,QAAQ,EAAE,CAAC;SACvB;KACJ;IAED,OAAO;QACH,KAAK,EAAE;YACH,GAAG,aAAa;YAChB,GAAG,WAAW;SACR;KACb,CAAC;AACN,CAAC;AAzBD,wCAyBC"}
+{"version":3,"file":"processRequest.js","sourceRoot":"","sources":["../../src/adapter-nextjs/processRequest.ts"],"names":[],"mappings":";;;;;;;;;;;;;;AAEA,gCAAuD;AAGvD,SAAgB,cAAc,CAC1B,OAAkC,EAClC,aAA4B,EAC5B,YAAqB,EACrB,WAA8C;IAEtC,IAAA,MAAM,GAAY,OAAO,OAAnB,EAAE,KAAK,GAAK,OAAO,MAAZ,CAAa;IAElC,IAAI,CAAC,aAAa,CAAC,cAAc,EAAE;QAC/B,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;KAC7B;IAED,IAAI,YAAY,EAAE;QACd,IAAM,QAAQ,GAAG,IAAA,mCAA4B,EAAC,aAAa,EAAE,MAAM,EAAE,YAAY,EAAE,KAAK,CAAC,CAAC;QAC1F,IAAI,QAAQ,EAAE;YACV,OAAO,EAAE,QAAQ,UAAA,EAAE,CAAC;SACvB;KACJ;IAED,OAAO;QACH,KAAK,EAAE,sBACA,aAAa,GACb,WAAW,CACR;KACb,CAAC;AACN,CAAC;AAzBD,wCAyBC"}