@enonic/nextjs-adapter 3.0.0-RC3 → 3.0.0-RC5

package/README.md

@@ -4,27 +4,33 @@
 
 ## Installation
 
----
-
 ```bash
 npm i --save @enonic/nextjs-adapter
 ```
 
 ## Usage
 
----
+All functions and views are split into 4 categories by usage:
+
+- `@enonic/nextjs-adapter` -- can be used both on server and client sides
+- `@enonic/nextjs-adapter/server` -- can only be used on server side
+- `@enonic/nextjs-adapter/client` -- can only be used on client side
+- `@enonic/nextjs-adapter/views/...` -- views folder, every view has its own file with a default export
 
-Just import required functions and views in your project:
+Here's the usage example in your project:
 
 ```tsx
-// all functions and interfaces are accessible at the library root
-import {fetchContent} from "@enonic/nextjs-adapter";
+// server-side functions are accessible at /server
+import {fetchContent} from "@enonic/nextjs-adapter/server";
 
 // views are placed in a folder called `views` and are default exports in files
 import MainView from "@enonic/nextjs-adapter/views/MainView"
 
 // ...
-const props = await fetchContent(path, context);
+const props = await fetchContent(path, {
+    contentPath: '/content/path',
+    locale: 'en',
+});
 // ...
 
 return <MainView {...props}/>
@@ -32,26 +38,26 @@ return <MainView {...props}/>
 
 ## API
 
----
+### <a id="server-side"></a>Server-side only functions
 
-### Functions
+They are available at `@enonic/nextjs-adapter/server`
 
-They are available at the library root at `@enonic/nextjs-adapter`
+<br/>
 
 #### <a id="fetch-content"></a>`fetchContent(contentPath: string | string[], context: Context) => Promise<FetchContentResult>`
 
 Fetches the content/component by path with component queries optimization, page structure as well as runtime info calculation. This is the
 main method for querying content.
 
-| Argument  | Description                           |
-|-----------|---------------------------------------|
-| `path`    | Path to content                       |
-| `context` | Execution context provided by Next.js |
+| Argument  | Description       |
+|-----------|-------------------|
+| `path`    | Path to content   |
+| `context` | Execution context |
 
 Usage:
 
 ```tsx
-import {fetchContent} from '@enonic/nextjs-adapter';
+import {fetchContent} from '@enonic/nextjs-adapter/server';
 
 const response = fetchContent('/path/to/content', context);
 ```
@@ -71,22 +77,29 @@ type FetchContentResult = {
 };
 ```
 
----
+<br/>
 
-#### <a id="fetch-guillotine"></a>`fetchGuillotine(apiUrl: string, body: ContentApiBaseBody, headers?: {}) => Promise<GuillotineResult>`
+#### <a id="fetch-guillotine"></a>`fetchGuillotine(apiUrl: string, mapping: LocaleMapping, options?: FetchOptions) => Promise<GuillotineResult>`
 
 Makes a custom request to Guillotine. Used by [fetchContent()](#fetch-content) method.
 
-| Argument  | Description                                             |
-|-----------|---------------------------------------------------------|
-| `apiUrl`  | Guillotine API URL                                      |
-| `body`    | Body of the request                                     |
-| `headers` | Object of custom headers with string values. _Optional_ |
+| Argument  | Description                                       |
+|-----------|---------------------------------------------------|
+| `apiUrl`  | Guillotine API URL                                |
+| `mapping` | [Mapping](#locale-mapping-type) locale to project |
+| `options` | Request and Next.js config options _(Optional)_   |
 
 Usage:
 
 ```tsx
-import {fetchGuillotine} from '@enonic/nextjs-adapter';
+import {fetchGuillotine} from '@enonic/nextjs-adapter/server';
+import {getLocaleMapping} from '@enonic/nextjs-adapter';
+
+const apiUrl = 'http://domain:8000/graphql/api';
+
+const mapping = getLocaleMapping({
+    contentPath: '/current/content/path',
+});
 
 const body = {
     query: 'qraphql query as string',
@@ -99,7 +112,17 @@ const headers = {
     'custom-header': 'header-value',
 };
 
-const result = fetchGuillotine('http://domain:8000/graphql/api', body, headers);
+const opts = {
+    body,
+    headers,
+    method: 'GET',
+    next: {
+        revalidate: 60,
+        tags: ['tag1', 'tag2'],
+    }
+};
+
+const result = fetchGuillotine(apiUrl, mapping, opts);
 ```
 
 Response type:
@@ -114,23 +137,29 @@ type GuillotineResult = {
 };
 ```
 
----
+<br/>
 
-#### `fetchFromApi(apiUrl: string, body: ContentApiBaseBody, headers?: {}, method?: string) => Promise<any>`
+#### `fetchFromApi(apiUrl: string, mapping: LocaleMapping, options?: FetchOptions) => Promise<GuillotineResponseJson>`
 
 Makes custom third-party service request. Used by the [fetchGuillotine()](#fetch-guillotine) method.
 
-| Argument  | Description                                                                        |
-|-----------|------------------------------------------------------------------------------------|
-| `apiUrl`  | Service API URL                                                                    |
-| `body`    | Body of the request                                                                |
-| `headers` | Object of custom headers with string values. _Optional_                            |
-| `method`  | Method of the request: `HEAD`, `POST`, `GET`, etc. _Optional, defaults to `POST`._ |
+| Argument  | Description                                       |
+|-----------|---------------------------------------------------|
+| `apiUrl`  | Service API URL                                   |
+| `mapping` | [Mapping](#locale-mapping-type) locale to project |
+| `options` | Request and Next.js config options _(Optional)_   |
 
 Usage:
 
 ```tsx
-import {fetchFromApi} from '@enonic/nextjs-adapter';
+import {fetchFromApi} from '@enonic/nextjs-adapter/server';
+import {getLocaleMapping} from '@enonic/nextjs-adapter';
+
+const apiUrl = 'http://domain:8000/graphql/api';
+
+const mapping = getLocaleMapping({
+    contentPath: '/current/content/path',
+});
 
 const body = {
     query: 'qraphql query as string',
@@ -143,17 +172,144 @@ const headers = {
     'custom-header': 'header-value',
 }
 
-const result = fetchFromApi('http://domain:8000/graphql/api', body, headers, 'GET');
+const opts = {
+    body,
+    headers,
+    method: 'POST',
+    next: {
+        revalidate: 60,
+        tags: ['tag1', 'tag2'],
+    }
+};
+
+const result = fetchFromApi(apiUrl, mapping, opts);
+```
+
+<br/>
+
+#### <a id="fetch-paths-for-all-locales"></a>`fetchContentPathsForAllLocales(path: string, query?: string, count?: number) => Promise<ContentPathItem[]>`
+
+Loads all content paths for all locales. Generally used for static site generation.
+
+| Argument | Description                                       |
+|----------|---------------------------------------------------|
+| `apiUrl` | Service API URL                                   |
+| `query`  | Request and Next.js config options _(Optional)_ * |
+| `count`  | Max result count _(Optional, defaults to 999)_    |
+
+&ast; Default query gets up to `count` results, sorts them by `modifiedTime` and excludes following content types:
+
+```
+"base:shortcut", 
+"portal:fragment", 
+"portal:template-folder", 
+"portal:page-template", 
+"media:*"
+```
+
+Usage:
+
+```tsx
+import {fetchContentPathsForAllLocales} from '@enonic/nextjs-adapter/server';
+
+const contentPaths = fetchContentPathsForLocale('/', 'custom graphql query', 1001);
+```
+
+<br/>
+
+#### `fetchContentPathsForLocale(path: string, mapping: LocaleMapping, query?: string, count?: number) => Promise<ContentPathItem[]>`
+
+Loads all content paths for the current locale. Generally used for static site generation.
+Used by [fetchContentPathsForAllLocales()](#fetch-paths-for-all-locales)
+
+| Argument  | Description                                                                                         |
+|-----------|-----------------------------------------------------------------------------------------------------|
+| `apiUrl`  | Service API URL                                                                                     |
+| `mapping` | [Mapping](#locale-mapping-type) locale to project                                                   |
+| `query`   | Request and Next.js config options _(Optional, [default value here](#fetch-paths-for-all-locales))_ |
+| `count`   | Max result count _(Optional, defaults to 999)_                                                      |
+
+Usage:
+
+```tsx
+import {fetchContentPathsForLocale} from '@enonic/nextjs-adapter/server';
+import {getLocaleMapping} from '@enonic/nextjs-adapter';
+
+const mapping = getLocaleMapping({
+    contentPath: '/current/content/path',
+});
+
+const contentPaths = fetchContentPathsForLocale('/', mapping, 'custom graphql query', 1001);
+```
+
+<br/>
+
+### <a id="client-side"></a>Client-side only functions
+
+They are available at `@enonic/nextjs-adapter/client`
+
+<br/>
+
+#### <a id="locale-context-provider"></a>`<LocaleContextProvider locale="en">`
+
+Create a React.js context that allows child elements to access and modify current locale as well as localize static texts for current
+locale. See [useLocaleContext()](#use-locale-context) method for example.
+
+| Argument | Type     | Description                  |
+|----------|----------|------------------------------|
+| `locale` | `String` | Set the initial locale value |
+
+Usage:
+
+```tsx
+import {LocaleContextProvider} from '@enonic/nextjs-adapter/client';
+
+<LocaleContextProvider locale="en"> ...child elements... </LocaleContextProvider>
+```
+
+<br/>
+
+#### <a id="use-locale-context"></a>`useLocaleContext() => LocaleContextType`
+
+Methods to access and modify current locale as well as localize static texts, where `LocaleContextType` is:
+
+```tsx
+interface LocaleContextType {
+    dictionary: Dict
+    locale: string
+    localize: (key: string, ...args: any[]) => string
+    setLocale: (locale: string) => Promise<Dict>
+}
+```
+
+Usage:
+
+```tsx
+'use client';
+
+import {useLocaleContext} from '@enonic/nextjs-adapter/client';
+
+export default function ClientSideComponent() {
+    const {locale, localize} = useLocaleContext();
+    const localizedText = localize('text.key');
+    // ...
+}
 ```
 
----
+<br/>
+
+### <a id="multi-side"></a>Both client and server-side functions
+
+They are available at `@enonic/nextjs-adapter`
 
-#### `getUrl(url: string, meta: MetaData) => string`
+<br/>
 
-Converts an absolute URL to the relative one for current viewer (Next.js/Enonic XP).
+#### <a id="get-url"></a>`getUrl(url: string, meta: MetaData) => string`
+
+Converts a site-relative or absolute URL to relative one for current viewer (Next.js/Enonic XP). Also takes care of locale if needed.
 
 > **INFO:** For your URLs to work both in Enonic XP and Next.js you need to:
-> 1. Query absolute URLs from guillotine
+> 1. Query site-relative or absolute URLs from guillotine
 > 2. Wrap them with `getUrl()` function in the views
 
 | Argument | Description                                             |
@@ -166,10 +322,34 @@ Usage:
 ```tsx
 import {getUrl} from '@enonic/nextjs-adapter';
 
-const urlRelativeToViewer = getUrl('http://domain:8000/graphql/api', meta);
+const urlRelativeToViewer = getUrl('/some/content/url', meta);
 ```
 
----
+<br/>
+
+#### <a id="get-asset"></a>`getAsset(url: string, meta: MetaData) => string`
+
+Converts a local asset URL to relative one for current viewer (Next.js/Enonic XP). It doesn't append locales unlike [getUrl()]
+(#get-url).
+
+> **INFO:** For your URLs to work both in Enonic XP and Next.js you need to:
+> 1. Use relative URL to local asset
+> 2. Wrap them with `getAsset()` function in the views
+
+| Argument | Description                                             |
+|----------|---------------------------------------------------------|
+| `url`    | asset URL you want to transform                         |
+| `meta`   | Runtime data returned by [fetchContent](#fetch-content) |
+
+Usage:
+
+```tsx
+import {getAsset} from '@enonic/nextjs-adapter';
+
+const urlRelativeToViewer = getAsset('/some/asset/url', meta);
+```
+
+<br/>
 
 #### <a id="rich-text-query"></a>`richTextQuery(fieldName: string) => string`
 
@@ -196,14 +376,40 @@ const query = `query($path:ID!){
 }`;
 ```
 
+<br/>
+
+#### `validateData(props: FetchContentResult) => void`
+
+Validates data returned by [fetchContent()](#fetch-content) method. Throws an error or notFound() if data is invalid.
+
+| Argument | Description                 |
+|----------|-----------------------------|
+| `props`  | `FetchContentResult` object |
+
+Usage:
+
+```tsx
+import {fetchContent} from '@enonic/nextjs-adapter/server';
+import {validateData} from '@enonic/nextjs-adapter';
+
+const data = fetchContent({
+    contentPath: '/path/to/content',
+    locale: 'en',
+});
+
+validateData(data);
+```
+
+<br/>
+
 ### `ComponentRegistry`
 
 Registry containing definitions of all components (i.e. pages, parts, layouts, macros, etc. ). It is used in the runtime by `nextjs-adapter`
 to make component queries and render components. It has several public methods:
 
----
+<br/>
 
-#### `setCommonQuery(query: SelectedQueryMaybeVariablesFunc): void`
+#### `static setCommonQuery(query: SelectedQueryMaybeVariablesFunc): void`
 
 Sets up a common query that is going to be executed along with component queries and passed to every component on the page.
 
@@ -228,9 +434,9 @@ const query = {
 ComponentRegistry.setCommonQuery(query);
 ```
 
----
+<br/>
 
-#### `getCommonQuery(): SelectedQueryMaybeVariablesFunc`
+#### `static getCommonQuery(): SelectedQueryMaybeVariablesFunc`
 
 Gets the common query definition.
 
@@ -255,9 +461,9 @@ import {ComponentRegistry} from '@enonic/nextjs-adapter';
 const query = ComponentRegistry.getCommonQuery();
 ```
 
----
+<br/>
 
-#### `getByComponent(component: PageComponent): ComponentDefinition | undefined`
+#### `static getByComponent(component: PageComponent): ComponentDefinition | undefined`
 
 Gets component definition from the ComponentRegistry.
 
@@ -285,19 +491,19 @@ interface ComponentDefinition {
 }
 ```
 
----
+<br/>
 
-#### `addMacro(name: string, obj: ComponentDefinition): void`
+#### `static addMacro(name: string, obj: ComponentDefinition): void`
 
-#### `addPart(name: string, obj: ComponentDefinition): void`
+#### `static addPart(name: string, obj: ComponentDefinition): void`
 
-#### `addLayout(name: string, obj: ComponentDefinition): void`
+#### `static addLayout(name: string, obj: ComponentDefinition): void`
 
-#### `addCPage(name: string, obj: ComponentDefinition): void`
+#### `static addCPage(name: string, obj: ComponentDefinition): void`
 
-#### `addContentType(name: string, obj: ComponentDefinition): void`
+#### `static addContentType(name: string, obj: ComponentDefinition): void`
 
-#### `addComponent(name: string, obj: ComponentDefinition): void`
+#### `static addComponent(name: string, obj: ComponentDefinition): void`
 
 Saves the component definition in ComponentRegistry by name.
 
@@ -319,19 +525,19 @@ const definition = {}
 ComponentRegistry.addMacro('macro-name', definition);
 ```
 
----
+<br/>
 
-#### `getMacro(name: string): ComponentDefinition | undefined`
+#### `static getMacro(name: string): ComponentDefinition | undefined`
 
-#### `getPart(name: string): ComponentDefinition | undefined`
+#### `static getPart(name: string): ComponentDefinition | undefined`
 
-#### `getLayout(name: string): ComponentDefinition | undefined`
+#### `static getLayout(name: string): ComponentDefinition | undefined`
 
-#### `getPage(name: string): ComponentDefinition | undefined`
+#### `static getPage(name: string): ComponentDefinition | undefined`
 
-#### `getContentType(name: string): ComponentDefinition | undefined`
+#### `static getContentType(name: string): ComponentDefinition | undefined`
 
-#### `getComponent(name: string): ComponentDefinition | undefined`
+#### `static getComponent(name: string): ComponentDefinition | undefined`
 
 Gets the component definition stored in ComponentRegistry by its name.
 
@@ -351,19 +557,19 @@ const definition = ComponentRegistry.getMacro('macro-name');
 
 Response type: [component definition](#comp-def)
 
----
+<br/>
 
-#### `getMacros(): ComponentDefinition[]`
+#### `static getMacros(): ComponentDefinition[]`
 
-#### `getParts(): ComponentDefinition[]`
+#### `static getParts(): ComponentDefinition[]`
 
-#### `getLayouts(): ComponentDefinition[]`
+#### `static getLayouts(): ComponentDefinition[]`
 
-#### `getPages(): ComponentDefinition[]`
+#### `static getPages(): ComponentDefinition[]`
 
-#### `getContentTypes(): ComponentDefinition[]`
+#### `static getContentTypes(): ComponentDefinition[]`
 
-#### `getComponents(): ComponentDefinition[]`
+#### `static getComponents(): ComponentDefinition[]`
 
 Gets all component definitions stored in ComponentRegistry.
 
@@ -379,33 +585,37 @@ const macros = ComponentRegistry.getMacros();
 
 Response type: List of [component definitions](#comp-def)
 
+<br/>
+
 ### `UrlProcessor`
 
 Helper singleton for processing URLs.
 
----
+<br/>
 
-#### <a id="process"></a>`static process(url: string, meta: MetaData): string`
+#### <a id="process"></a>`static process(url: string, meta: MetaData, serverSide = false, isResource = false): string`
 
 Processes the absolute URL to become relative for the current viewer, while keeping in mind Next.js assets and Enonic XP binary content
 links
 
-> **NOTE:** There is an alias to this function called `getUrl()` available at `@enonic/nextjs-adapter`
+> **NOTE:** There are convenience aliases to this function called [getUrl()](#get-url) and [getAsset()](#get-asset)
 
-| Argument | Description                                             |
-|----------|---------------------------------------------------------|
-| `url`    | Absolute URL                                            |
-| `meta`   | Runtime data returned by [fetchContent](#fetch-content) |
+| Argument     | Description                                                                  |
+|--------------|------------------------------------------------------------------------------|
+| `url`        | Absolute URL                                                                 |
+| `meta`       | Runtime data returned by [fetchContent](#fetch-content)                      |
+| `serverSide` | Whether URL is going to be used on the server side _(Skips adding basePath)_ |
+| `isResource` | Whether URL is a resource _(Skips adding locale)_                            |
 
 Usage:
 
 ```tsx
 import {UrlProcessor} from '@enonic/nextjs-adapter';
 
-const url = UrlProcessor.process('http://www.some.site.com/url/to/content', meta);
+const url = UrlProcessor.process('http://www.some.site.com/url/to/content', meta, true, false);
 ```
 
----
+<br/>
 
 #### `static processSrcSet(srcset: string, meta: MetaData): string`
 
@@ -424,11 +634,12 @@ import {UrlProcessor} from '@enonic/nextjs-adapter';
 const url = UrlProcessor.processSrcSet('<srcset value>', meta);
 ```
 
----
+<br/>
 
 #### `static setSiteKey(key: string): void`
 
-Sets the site key value that is needed for correct URL processing. It is automatically done by `nextjs-adapter` so you don't have to do it.
+Sets the site key value that is needed for correct absolute URL processing. It is automatically done by `nextjs-adapter` so you don't
+have to do it.
 
 > **WARNING:** Overriding this value may result in wrong URL processing !
 
@@ -444,7 +655,7 @@ import {UrlProcessor} from '@enonic/nextjs-adapter';
 UrlProcessor.setSiteKey('<site key>');
 ```
 
----
+<br/>
 
 #### `static isMediaLink(ref: string, linkData: LinkData[]): boolean`
 
@@ -465,7 +676,7 @@ import {UrlProcessor} from '@enonic/nextjs-adapter';
 UrlProcessor.isMediaLink('<link ref>', linkData);
 ```
 
----
+<br/>
 
 #### `static isContentImage(ref: string, imageData: ImageData[]): boolean`
 
@@ -486,30 +697,234 @@ import {UrlProcessor} from '@enonic/nextjs-adapter';
 UrlProcessor.isContentImage('<image ref>', imageData);
 ```
 
+<br/>
+
+### Enonic XP locale mapping functions
+
+In order to create association between locale and Enonic XP project, `ENONIC_MAPPINGS` environment variable should be set.
+Functions for reading those mappings are available at `@enonic/nextjs-adapter`.
+
+<br/>
+
+#### `getLocaleMapping(context: Context): LocaleMapping`
+
+| Argument  | Description      |
+|-----------|------------------|
+| `context` | `Context` object |
+
+Usage:
+
+```tsx
+import {getLocaleMapping} from '@enonic/nextjs-adapter';
+
+const mapping = getLocaleMapping({
+    contentPath: '/current/content/path',
+    locale: 'en',
+});
+```
+
+<a id="locale-mapping-type"></a>Response type:
+
+```tsx
+export interface LocaleMapping {
+    default: boolean
+    project: string
+    site: string
+    locale: string
+}
+```
+
+<br/>
+
+#### `getLocaleMappingByProjectId(projectId?: string, useDefault = true): LocaleMapping`
+
+| Argument     | Description                                                |
+|--------------|------------------------------------------------------------|
+| `projectId`  | Enonic project ID _(Optional)_                             |
+| `useDefault` | Use default locale as fallback _(Optional, default: true)_ |
+
+Usage:
+
+```tsx
+import {getLocaleMappingByProjectId} from '@enonic/nextjs-adapter';
+
+const mapping = getLocaleMappingByProjectId('project-id', true);
+```
+
+[Response type](#locale-mapping-type)
+
+<br/>
+
+#### `getLocaleMappingByLocale(locale?: string, useDefault = true): LocaleMapping`
+
+| Argument     | Description                                                |
+|--------------|------------------------------------------------------------|
+| `locale`     | locale ID _(Optional)_                                     |
+| `useDefault` | Use default locale as fallback _(Optional, default: true)_ |
+
+Usage:
+
+```tsx
+import {getLocaleMappingByLocale} from '@enonic/nextjs-adapter';
+
+const mapping = getLocaleMappingByLocale('en', true);
+```
+
+[Response type](#locale-mapping-type)
+
+<br/>
+
+#### `getRequestLocaleInfo(context: Context): LocaleMapping`
+
+Attempts to get the locale info from the request. Along with that it also returns the default locale and all configured locales.
+
+| Argument  | Description      |
+|-----------|------------------|
+| `context` | `Context` object |
+
+Usage:
+
+```tsx
+import {getRequestLocaleInfo} from '@enonic/nextjs-adapter';
+
+const mapping = getRequestLocaleInfo({
+    contentPath: '/current/content/path',
+    locale: 'en',
+});
+```
+
+Response type:
+
+```tsx
+interface LocaleInfo {
+    locale: string,
+    locales: string[],
+    defaultLocale: string
+}
+```
+
+<br/>
+
+### `I18n` localization functions
+
+These functions can be used both on server and client sides, but it is recommended to
+use [native React.js context](#locale-context-provider) classes for client-side localization.
+
+<br/>
+
+#### `static I18n.setLocale(locale: string): Promise<Dict>`
+
+Sets the current locale and returns the dictionary for it.
+
+| Argument | Description          |
+|----------|----------------------|
+| `locale` | Locale id, i.e. `en` |
+
+Usage:
+
+```tsx
+import {I18n} from '@enonic/nextjs-adapter';
+
+const dict = await I18n.setLocale('en');
+```
+
+<a id="dict-type"></a>Response type:
+
+```tsx
+interface Dict {
+    [key: string]: string
+}
+```
+
+<br/>
+
+#### `static I18n.localize(key: string, ...args: any[]): string`
+
+Localizes the static text by key and replaces placeholders with provided arguments.
+
+| Argument  | Description        |
+|-----------|--------------------|
+| `key`     | text key           |
+| `...args` | template arguments |
+
+Usage:
+
+```tsx
+import {I18n} from '@enonic/nextjs-adapter';
+
+const localizedText = I18n.localize('text.key', 'value1', 'value2');
+```
+
+<br/>
+
+#### `static I18n.getLocale(): string`
+
+Returns the current locale.
+
+Usage:
+
+```tsx
+import {I18n} from '@enonic/nextjs-adapter';
+
+const locale = I18n.getLocale();
+```
+
+<br/>
+
+#### `static I18n.getDictionary(): Dict`
+
+Returns dictionary for the current locale.
+
+Usage:
+
+```tsx
+import {I18n} from '@enonic/nextjs-adapter';
+
+const dict = I18n.getDictionary();
+```
+
+[Response type](#dict-type)
+
+<br/>
+
 ### Utility functions
 
-There is also a number of utility variables and functions available at `@enonic/nextjs-adapter`.
+There is also a number of utility constants and functions available at `@enonic/nextjs-adapter`.
 
----
+<br/>
 
 ```tsx
-IS_DEV_MODE;            // True if current mode == development
+import {CATCH_ALL} from './constants';
+
+IS_DEV_MODE;                // True if current mode == development
+
+APP_NAME;                   // Name of the app defined in .env files
+
+APP_NAME_UNDERSCORED;       // APP_NAME with underscores instead of dots
+
+APP_NAME_DASHED;            // APP_NAME with dashes instead of dots
+
+CATCH_ALL;                  // Catch all component name
+
+PORTAL_COMPONENT_ATTRIBUTE; // Portal component attribute name
 
-APP_NAME;               // Name of the app defined in .env files
+PORTAL_REGION_ATTRIBUTE;    // Portal region attribute name
 
-APP_NAME_UNDERSCORED;   // APP_NAME with underscores instead of dots
+JSESSIONID_HEADER;          // JSESSIONID header name
 
-APP_NAME_DASHED;        // APP_NAME with dashes instead of dots
+PROJECT_ID_HEADER;          // Project ID header name
 
-SITE_KEY;               // Site key defined in .env files
+RENDER_MODE_HEADER;         // Render mode header name
 
-enum XP_REQUEST_TYPE {
+XP_BASE_URL_HEADER;         // XP base URL header name
+
+enum XP_REQUEST_TYPE {      // Enum for XP request types
     COMPONENT = 'component',
     TYPE = 'type',
     PAGE = 'page',
 }
 
-enum RENDER_MODE {
+enum RENDER_MODE {          // Enum for render modes
     INLINE = 'inline',
     EDIT = 'edit',
     PREVIEW = 'preview',
@@ -518,7 +933,7 @@ enum RENDER_MODE {
     NEXT = 'next',
 }
 
-enum XP_COMPONENT_TYPE {
+enum XP_COMPONENT_TYPE {    // Enum for XP component types
     PART = 'part',
     LAYOUT = 'layout',
     TEXT = 'text',
@@ -531,13 +946,16 @@ const sanitizeGraphqlName = (text: string) => string;
 
 // Returns common part of 2 strings
 const commonChars = (s1?: string, s2?: string) => string;
+
+// Returns full content api URL with current project and branch appended
+const getContentApiUrl = (context: Context) => string;
 ```
 
 ### Views
 
 They are located in `@enonic/nextjs-adapter/views` folder. Each view is a default export in the corresponding file.
 
----
+<br/>
 
 #### `<MainView common="common" data="data" page="page" meta="meta">`
 
@@ -567,7 +985,7 @@ export async function getServerSideProps(context: Context) {
 export default MainView;
 ```
 
----
+<br/>
 
 #### `<StaticContent condition="true" tag="div">`
 
@@ -586,7 +1004,7 @@ import StaticContent from '@enonic/nextjs-adapter/views/StaticContent';
 <StaticContent condition={true} tag="div"> ...child elements... </StaticContent>
 ```
 
----
+<br/>
 
 #### <a id="rich-text-view"></a>`<RichTextView className="css-class" tag="section" data={data} meta={meta}, renderMacroInEditMode="true", customReplacer={customReplacerFn}>`
 
@@ -612,7 +1030,7 @@ import RichTextView from '@enonic/nextjs-adapter/views/RichTextView';
 <RichTextView data={richTextData} meta={meta} tag="section" className="rich-text-view" renderMacroInEditMode="false"></RichTextView>
 ```
 
----
+<br/>
 
 #### `<Regions page={page} meta={meta} name="main" common={common}>`
 
@@ -636,19 +1054,21 @@ import StaticContent from '@enonic/nextjs-adapter/views/StaticContent';
 
 ## Known problems
 
----
 
 In some cases, when using in NextJS application, a build errors related to the JSX may appear, that state the following:
+
 ```
 You may need an appropriate loader to handle this file type, currently no loaders are configured to process this file. See https://webpack.js.org/concepts#loaders
 ```
+
 To prevent these errors, it is necessary to transpile the library using something
 like [`next-transpile-modules`](https://www.npmjs.com/package/next-transpile-modules).
 Install it as dev dependency and call it explicitly from you NextJS config:
 
 `next.config.js`
+
 ```js
 const withTM = require('next-transpile-modules')(['@enonic/nextjs-adapter']);
 
 module.exports = withTM({});
-```
+```