56 |
--------------------------------------------------------------------------------
/_includes/page-toc.md:
--------------------------------------------------------------------------------
1 | ---
2 |
3 | ## Table of contents
4 | {: .no_toc .text-delta }
5 |
6 | - TOC
7 | {:toc}
8 |
--------------------------------------------------------------------------------
/_includes/preset/demo.md:
--------------------------------------------------------------------------------
1 | {% if tenancy == 'mst' %}
2 | ##### Tenancy
3 | This preset uses a MST design.
4 |
5 | Therefore, there are 2 different demo available at:
6 | 1. [https://nrn-{{preset}}-**c1**.vercel.app/](https://nrn-{{preset}}-c1.vercel.app/), and its preview at [https://nrn-{{preset}}-**c1**-preview.vercel.app/](https://nrn-{{preset}}-c1-preview.vercel.app/)
7 | 1. [https://nrn-{{preset}}-**c2**.vercel.app/](https://nrn-{{preset}}-c2.vercel.app/), and its preview at [https://nrn-{{preset}}-**c2**-preview.vercel.app/](https://nrn-{{preset}}-c2-preview.vercel.app/)
8 |
9 | Both demo have been generated using the same source code, the two demo live in a completely separated server and won't be affected by each other (MST design)
10 |
11 | The same database is used by both tenants (MT design), but the displayed content is specific to each tenant (theme, logo, etc.) (ST design)
12 |
13 | Overall, we use a hybrid tenancy design that we name MST, which is due to a compromise between complexity (only one DB/API (AKA MT)) and security/performances/risk (multiple servers to avoid massive downtime of all customers at once (AKA ST))
14 | {% endif %}
15 |
16 |
17 |
18 | {% if rendering == 'ssr' %}
19 | ##### Server side rendering
20 | Requests are performed in real-time (SSR), each request send a GraphQL query (put aside client/server caching)
21 |
22 | Of course, if the DB itself gets down, all tenants would be impacted at once, which is quite a critical issue (we may protect ourselves against such an outage using [a proxy server cache](https://github.com/UnlyEd/GraphCMS-cache-boilerplate))
23 | {% endif %}
24 |
25 |
26 |
27 | {% if rendering == 'hybrid' %}
28 | ##### Static pages
29 | Most pages are built statically (SSG), there are some SSR pages to showcase hybrid usage (per-page rendering mode).
30 |
31 | Due to SSG, the whole app is extremely fast, and very resilient. It basically cannot crash on SSG pages, even if our underlying providers are taken down.
32 |
33 | Even if critical vendors are being used (e.g: Locize, GraphCMS, Airtable - because they hold our data), it doesn't matter if there is an outage on their side because we only depend on them during **build time**.
34 |
35 | Also, the cost is reduced when using SSG, compared to using SSR because we avoid real-time requests to extra services (e.g: Locize, Vercel, GraphCMS).
36 | {% endif %}
37 |
--------------------------------------------------------------------------------
/_includes/preset/title.md:
--------------------------------------------------------------------------------
1 | > {{- tenancy | upcase -}}
2 |
3 | {%- if analytics == 'amplitude' -%}
4 | Amplitude
5 | {%- endif -%}
6 |
7 | {%- if gql-api == 'gcms' -%}
8 | GraphCMS
9 | {%- elsif gql-api == 'airtable' -%}
10 | Airtable
11 | {%- endif -%}
12 |
13 | {%- if i18n == 'locize' -%}
14 | Locize
15 | {%- endif -%}
16 |
17 | {%- if monitoring == 'sentry' -%}
18 | Sentry
19 | {%- endif -%}
20 |
--------------------------------------------------------------------------------
/_includes/vendors/all-vendors-table.md:
--------------------------------------------------------------------------------
1 | | Vendor | Tag | Has free trial | Has free plan | Potential discounts | Install guide |
2 | |:-------|:----|:---------------|:--------------|:--------------------|---------------|
3 | {% include vendors/vendor-row-vercel.md %}{% include vendors/vendor-row-amplitude.md %}{% include vendors/vendor-row-graphcms.md %}{% include vendors/vendor-row-airtable.md %}{% include vendors/vendor-row-stacker.md %}{% include vendors/vendor-row-locize.md %}{% include vendors/vendor-row-sentry.md %}
4 |
--------------------------------------------------------------------------------
/_includes/vendors/vendor-row-airtable.md:
--------------------------------------------------------------------------------
1 | | [Airtable](https://airtable.com/pricing?ref=unly-nrn) | `at` | :heavy_check_mark: Free up to 1200 records per base (or 2Go storage) | :x: | If you're interested about Airtable, [here is how to get $2k credits for $50](https://www.joinsecret.com/fr/offers/airtable-coupon-1800) (I've personally used it!) | [Guide](../guides/airtable-api/setup-airtable) |
2 |
--------------------------------------------------------------------------------
/_includes/vendors/vendor-row-amplitude.md:
--------------------------------------------------------------------------------
1 | | [Amplitude](https://amplitude.com/pricing?ref=unly-nrn) | `aptd` | :x: | :heavy_check_mark: [Up to 10 million events a month](https://amplitude.com/pricing?ref=unly-nrn) [1st year free](https://amplitude.com/startups?ref=unly-nrn) _(for startups and non-profit)_ | Don't provide discounts | [Guide](../guides/analytics/setup-amplitude) |
2 |
--------------------------------------------------------------------------------
/_includes/vendors/vendor-row-graphcms.md:
--------------------------------------------------------------------------------
1 | | [GraphCMS](https://graphcms.com/pricing?ref=unly-nrn) | `gmcs` | :heavy_check_mark: 2 weeks on **Growth** plan | :heavy_check_mark: | [15% discount for NRN users](../guides/graphql-api/setup-graphcms) + provides discounts for non-profit organisations | [Guide](../guides/graphql-api/setup-graphcms) |
2 |
--------------------------------------------------------------------------------
/_includes/vendors/vendor-row-locize.md:
--------------------------------------------------------------------------------
1 | | [Locize](https://locize.com/pricing.html?ref=unly-nrn) | `lcz` | :heavy_check_mark: 2 weeks | :x: | May provide discount for non-profit organisations, contact them at [support@locize.com](support@locize.com ) | [Guide](../guides/i18n/setup-locize) |
2 |
--------------------------------------------------------------------------------
/_includes/vendors/vendor-row-sentry.md:
--------------------------------------------------------------------------------
1 | | [Sentry](https://sentry.io/pricing?ref=unly-nrn) | `sty` | :heavy_check_mark: 2 weeks on **any** plan | :heavy_check_mark: | Don't provide discounts | [Guide](../guides/monitoring/setup-sentry) |
2 |
--------------------------------------------------------------------------------
/_includes/vendors/vendor-row-stacker.md:
--------------------------------------------------------------------------------
1 | | [Stacker](https://stacker.app/pricing?ref=unly-nrn) | Included when preset features Airtable | :heavy_check_mark: Free until you launch to production (no limit) | :x: | Get in touch with them (on [Slack](https://stacker-customers.slack.com)) to discuss discounts | [Guide](../guides/stacker-cms/setup-stacker) |
2 |
--------------------------------------------------------------------------------
/_includes/vendors/vendor-row-vercel.md:
--------------------------------------------------------------------------------
1 | | [Vercel](https://vercel.co/pricing?ref=unly-nrn) | Built-in | :x: | :heavy_check_mark: | Friendly pricing for [non-commercial usage](https://spectrum.chat/vercel/general/deploying-on-ziet-now~700e3286-551f-42d1-a289-df4cb52e23ea?m=MTU4MzgzMjg1MzAyOA==) | [Guide](../guides/online-hosting/setup-vercel) |
2 |
--------------------------------------------------------------------------------
/_includes/vendors/vendors-table.md:
--------------------------------------------------------------------------------
1 | {% if preset %}
2 | The following vendors are **built-in** with the preset `{{preset}}`.
3 | {% endif %}
4 |
5 | | Vendor | Tag | Has free trial | Has free plan | Potential discounts | Install guide |
6 | |:-------|:----|:---------------|:--------------|:--------------------|---------------|
7 | {% if hosting == 'vercel' %}{% include vendors/vendor-row-vercel.md %}{% endif %}{% if analytics == 'amplitude' %}{% include vendors/vendor-row-amplitude.md %}{% endif %}{% if gql-api == 'gcms' %}{% include vendors/vendor-row-graphcms.md %}{% endif %}{% if gql-api == 'airtable' %}{% include vendors/vendor-row-airtable.md %}{% include vendors/vendor-row-stacker.md %}{% endif %}{% if i18n == 'locize' %}{% include vendors/vendor-row-locize.md %}{% endif %}{% if monitoring == 'sentry' %}{% include vendors/vendor-row-sentry.md %}{% endif %}
8 |
--------------------------------------------------------------------------------
/_includes/vercel-online-hosting-pre-requisites.md:
--------------------------------------------------------------------------------
1 | You must **change the associated Vercel `scope`** (it uses NRN own scope by default, because it's required for our CI/CD Github Actions)
2 | - Remove the whole line `"scope": "team_qnVfSEVc2WwmOE1OYhZr4VST",` in **all** `vercel.*.json` files (this `scope` is NRN own scope, and you don't have permissions to access it, so you must remove it manually. We keep it there to make our own CI/CD works)
3 | - **Tip**: Don't forget `vercel.json` is a **symlink** and **shouldn't** to be modified (run `ln vercel.staging.json vercel.json` if you messed it up :wink:)
4 |
5 | You must **be authenticated to Vercel** from your local machine.
6 | Typically, if it's the first time you use Vercel you'll need to do it.
7 | - Run `npx vercel login`
8 | - **Windows**: You'll need to run `npx vercel login email@domain` instead, because it doesn't support interactive prompt.
9 |
10 | You must **configure all your Vercel secrets**.
11 | The list of required secrets depends on your preset and are listed in the `vercel*.json` file you're trying to deploy.
12 |
13 | To create a new secret, use `vercel secrets add nrn-secret secret-value`.
14 | If you create a secret with a wrong value, you will have to delete it and create it again (there is no update feature). See `vercel secrets --help`
15 | - **Tip**: If you ever need to store files as secrets (such as ssh keys), see [this solution](https://github.com/vercel/vercel/issues/749#issuecomment-533873759)
16 |
17 | See each vendor documentation for additional information.
18 |
--------------------------------------------------------------------------------
/_includes/windows-concerns.md:
--------------------------------------------------------------------------------
1 | - On Windows OS, the `yarn start:windows` command should be used instead of `yarn start`
2 | - That's because the `yarn start` command uses some bash script which aren't compatible with Windows (unless you're using WSL)
3 | - You might want to install [WSL on Windows 10](https://www.thewindowsclub.com/how-to-run-sh-or-shell-script-file-in-windows-10) to enable basic bash support
4 | - NRN v2 has been tested on Windows (on June 1st, 2020) and works correctly
5 | - **Tip**: We recommend [`nvm-windows`](https://github.com/coreybutler/nvm-windows/releases) as replacement for `nvm` (download the `nvm-setup.zip`)
6 | - When manually deploying (i.e: `yarn deploy`), the symbolic link for `vercel.json` (which points to another `vercel.*.json` file, depending on the preset) **will not work on Windows**, and you'll have to create a `vercel.json` yourself (just copy the content of any `vercel.*.json` file)
7 | - This is not a concern if you don't need to deploy manually from a Windows computer, as CI/CD will deploy properly (CI/CD runs under Unix)
8 |
9 | **Using Cygwin/Babun**
10 |
11 | It's possible to use Cygwin/Babun to simulate a unix-like local environment. It's not required.
12 |
13 | It's particularly useful if you encounter issues and can't use `wsl2`. (e.g: Not available on < Windows 10)
14 |
15 | If you don't use Cygwin/Babun, check out `wsl2`.
16 |
17 | - **Tip**: Babun support has been discontinued in 2019, but it still works perfectly.
18 | - **Tip**: **Windows 10** `wsl2` may provide a better experience - [What is wsl2?](https://docs.microsoft.com/en-us/windows/wsl/wsl2-about)
19 |
--------------------------------------------------------------------------------
/_sass/custom/custom.scss:
--------------------------------------------------------------------------------
1 | // XXX Overrides CSS styles - See https://pmarsceill.github.io/just-the-docs/docs/customization/#override-and-completely-custom-styles
2 |
3 | blockquote {
4 | background: #f9f9f9;
5 | border-left: 3px solid #a493f2;
6 | margin: 1.5em 10px;
7 | padding: 0.5em 10px;
8 |
9 | &:before,
10 | &:after {
11 | color: #a493f2;
12 | }
13 |
14 | &:before {
15 | content: '"';
16 | }
17 |
18 | &:after {
19 | content: '"';
20 | }
21 |
22 | p:first-child,
23 | p:last-child {
24 | display: inline;
25 | }
26 | }
27 |
28 | .pagination-section {
29 | display: flex;
30 | justify-content: space-between;
31 |
32 | &.space-even {
33 | justify-content: space-evenly;
34 | }
35 | }
36 |
37 | // Overrides https://github.com/jekyll/jemoji for better positioning alongside text
38 | img.emoji {
39 | top: 5px;
40 | position: relative;
41 | }
42 |
43 | h1 {
44 | code {
45 | font-size: 36px;
46 | }
47 | }
48 |
49 | h2 {
50 | code {
51 | font-size: 24px;
52 | }
53 | }
54 |
--------------------------------------------------------------------------------
/available-presets/index.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: Available presets
4 | nav_order: 25
5 | has_children: true
6 | has_toc: false
7 | ---
8 |
9 | # Available presets
10 |
11 |
12 | This page lists all presets, and their most important built-in features.
13 |
14 | This list is **meant to help you find the preset that best fit your needs**, depending on the **built-in features** that comes with each,
15 | and help you get started to build your own project based on this preset.
16 |
17 | Note that all presets also contains the "common features" [mentioned in the homepage](../#common-features-available-in-all-presets).
18 |
19 | - Make sure you understand [**what's a preset**](../concepts/presets) before going further.
20 | - Make sure you're up-to-date with the [terminology](../reference/terminology) being used.
21 |
22 |
23 | {% include page-toc.md %}
24 |
25 | ---
26 |
27 | ## How do I know which preset is best for me?
28 |
29 | [Check our guide](../concepts/presets#how-do-i-know-which-preset-is-best-for-me)
30 |
31 |
32 | ## Recommended presets
33 | {: .text_delta .label .label-green }
34 |
35 | - ### [`v2-mst-aptd-at-lcz-sty`](./v2-mst-aptd-at-lcz-sty)
36 | - MST (Multi Single Tenancy)
37 | - Analytics (Amplitude)
38 | - REST-ish API (Airtable)
39 | - CMS back office (Stacker)
40 | - I18n (Locize)
41 | - Monitoring (Sentry)
42 |
43 | - ### [`v2-mst-aptd-gcms-lcz-sty`](./v2-mst-aptd-gcms-lcz-sty)
44 | - MST (Multi Single Tenancy)
45 | - Analytics (Amplitude)
46 | - GraphQL API (GraphCMS)
47 | - I18n (Locize)
48 | - Monitoring (Sentry)
49 |
50 | ---
51 |
52 | ## Deprecated presets
53 | {: .text_delta .label .label-red }
54 |
55 | > All presets from previous major versions are automatically being deprecated
56 | >
57 | > Deprecation means we don't encourage using those presets anymore. Reasons can be various (outdated Next.js version, deprecated vendors, etc.)
58 |
59 | - ### [`v1-ssr-mst-aptd-gcms-lcz-sty`](./v1-ssr-mst-aptd-gcms-lcz-sty)
60 | - MST (Multi Single Tenancy)
61 | - Analytics (Amplitude)
62 | - GraphQL API (GraphCMS)
63 | - I18n (Locize)
64 | - Monitoring (Sentry)
65 |
--------------------------------------------------------------------------------
/available-presets/v1-ssr-mst-aptd-gcms-lcz-sty.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: v1-ssr-mst-aptd-gcms-lcz-sty
4 | parent: Available presets
5 | nav_order: 20
6 | ---
7 |
8 | {% capture preset %}{{ page.title }}{% endcapture %}
9 | {% assign rendering = 'ssr' %}
10 | {% assign tenancy = 'mst' %}
11 | {% assign hosting = 'vercel' %}
12 | {% assign i18n = 'locize' %}
13 | {% assign gql-api = 'gcms' %}
14 | {% assign monitoring = 'sentry' %}
15 | {% assign analytics = 'amplitude' %}
16 |
17 | ## `{{preset}}`
18 | {: .no_toc }
19 |
20 | {% include preset/title.md %}
21 |
22 | DEPRECATED
23 | {: .label .label-red }
24 |
25 | OFFICIAL
26 | {: .label .label-purple }
27 |
28 | March 2020
29 | {: .label .label-blue }
30 |
31 | {% include page-toc.md %}
32 |
33 | ---
34 |
35 | ### Overview
36 |
37 | > **This preset has been deprecated** in favor of [`v2-mst-aptd-gcms-lcz-sty`](./v2-mst-aptd-gcms-lcz-sty)
38 |
39 | | Preset | Diff PR | Pricing concerns |
40 | |:-------|:--------|:-----------------|
41 | | `{{preset}}` - [Branch](https://github.com/UnlyEd/next-right-now/tree/{{preset}}) | Identical | [Not free (Locize)](../reference/vendors) |
42 |
43 | ### Built-in features
44 |
45 | {% include features/features-table.md %}
46 |
47 | ### Demo
48 |
49 | {% include preset/demo.md %}
50 |
51 | ### Built-in 3rd party vendors
52 |
53 | {% include vendors/vendors-table.md %}
54 |
55 | ### Clone locally
56 |
57 | ```sh
58 | git clone https://github.com/UnlyEd/next-right-now.git nrn-{{preset}} && cd nrn-demo && git checkout {{preset}}
59 | ```
60 |
61 | This will create a `nrn-{{preset}}` folder in your current directory and checkout the `{{preset}}` git branch automatically.
62 |
63 | ### Local installation guide
64 |
65 | {% include installation-guide-full.md %}
66 |
67 | ### Advanced configuration
68 |
69 | {% include installation-guide-tips.md %}
70 |
--------------------------------------------------------------------------------
/available-presets/v2-mst-aptd-at-lcz-sty.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: v2-mst-aptd-at-lcz-sty
4 | parent: Available presets
5 | nav_order: 9
6 | ---
7 |
8 | {% capture preset %}{{ page.title }}{% endcapture %}
9 | {% assign rendering = 'hybrid' %}
10 | {% assign tenancy = 'mst' %}
11 | {% assign hosting = 'vercel' %}
12 | {% assign i18n = 'locize' %}
13 | {% assign gql-api = 'airtable' %}
14 | {% assign monitoring = 'sentry' %}
15 | {% assign analytics = 'amplitude' %}
16 |
17 | ## `{{preset}}`
18 | {: .no_toc }
19 |
20 | {% include preset/title.md %}
21 |
22 | OFFICIAL
23 | {: .label .label-purple }
24 |
25 | July 2020
26 | {: .label .label-blue }
27 |
28 | {% include page-toc.md %}
29 |
30 | ---
31 |
32 | ### Overview
33 |
34 | | Preset | Diff PR | Pricing concerns |
35 | |:-------|:--------|:-----------------|
36 | | `{{preset}}` - [Branch](https://github.com/UnlyEd/next-right-now/tree/{{preset}}) | [Compared to `v2-mst-aptd-gcms-lcz-sty`](https://github.com/UnlyEd/next-right-now/pull/86) | [Not free (Locize, Stacker)](../reference/vendors) |
37 |
38 | It was released in July 2020 to take over [`v2-mst-aptd-gcms-lcz-sty`](./v2-mst-aptd-gcms-lcz-sty) preset and provides a few more features CMS-related.
39 |
40 | In comparison, this preset features a built-in CMS (featuring Stacker) which plays very nicely with Airtable as a database (but can also use SalesForce and Google Sheets!).
41 | Also, it features "Markdown as JSX" advanced use-case, which may be very handy.
42 |
43 | ### Built-in features
44 |
45 | List of built-in features **specific to this preset**.
46 |
47 | > For an overview of features included in all presets, check out the ["Benefits" section](../#common-features-available-in-all-presets).
48 |
49 | {% include features/features-table.md %}
50 |
51 | ### Demo
52 |
53 | {% include preset/demo.md %}
54 |
55 | ### Storybook - UI components documentation
56 |
57 | Check out the [online Storybook documentation](https://nrn-v2-mst-aptd-at-lcz-sty-storybook.vercel.app/){:target="_blank"} for this preset.
58 |
59 | > Each preset has its own Storybook documentation, because a few components are different.
60 |
61 | ### Built-in 3rd party vendors
62 |
63 | {% include vendors/vendors-table.md %}
64 |
65 | ### Clone locally
66 |
67 | ```sh
68 | git clone https://github.com/UnlyEd/next-right-now.git nrn-{{preset}} && cd nrn-{{preset}} && git checkout {{preset}}
69 | ```
70 |
71 | This will create a `nrn-{{preset}}` folder in your current directory and checkout the `{{preset}}` git branch automatically.
72 |
73 | Cloning it once is enough, but it may be simpler to use one clone per preset if you're trying out multiple presets locally :wink:
74 |
75 | ### Local installation guide
76 |
77 | {% include installation-guide-full.md %}
78 |
79 | ### Advanced configuration
80 |
81 | {% include installation-guide-tips.md %}
82 |
--------------------------------------------------------------------------------
/available-presets/v2-mst-aptd-gcms-lcz-sty.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: v2-mst-aptd-gcms-lcz-sty
4 | parent: Available presets
5 | nav_order: 10
6 | ---
7 |
8 | {% capture preset %}{{ page.title }}{% endcapture %}
9 | {% assign rendering = 'hybrid' %}
10 | {% assign tenancy = 'mst' %}
11 | {% assign hosting = 'vercel' %}
12 | {% assign i18n = 'locize' %}
13 | {% assign gql-api = 'gcms' %}
14 | {% assign monitoring = 'sentry' %}
15 | {% assign analytics = 'amplitude' %}
16 |
17 | ## `{{preset}}`
18 | {: .no_toc }
19 |
20 | {% include preset/title.md %}
21 |
22 | OFFICIAL
23 | {: .label .label-purple }
24 |
25 | May 2020
26 | {: .label .label-blue }
27 |
28 | {% include page-toc.md %}
29 |
30 | ---
31 |
32 | ### Overview
33 |
34 | | Preset | Diff PR | Pricing concerns |
35 | |:-------|:--------|:-----------------|
36 | | `{{preset}}` - [Branch](https://github.com/UnlyEd/next-right-now/tree/{{preset}}) | [Compared to `v1-ssr-mst-aptd-gcms-lcz-sty`](https://github.com/UnlyEd/next-right-now/pull/68) | [Not free (Locize)](../reference/vendors) |
37 |
38 | It is very similar to [`v2-mst-aptd-at-lcz-sty`](./v2-mst-aptd-at-lcz-sty) which came out in July, 2020.
39 | Which uses a REST-ish API (featuring Airtable vendor) instead of GraphQL (featuring GraphCMS vendor).
40 |
41 | Depending on what you need/like the most (GraphQL vs REST), you may choose one or the other.
42 |
43 | Please note `v2-mst-aptd-at-lcz-sty` has since become the main preset, and provides a few very advanced features (e.g: Markdown as JSX), and a much better CMS (featuring Stacker CMS).
44 |
45 | ### Built-in features
46 |
47 | List of built-in features **specific to this preset**.
48 |
49 | > For an overview of features included in all presets, check out the ["Benefits" section](../#common-features-available-in-all-presets).
50 |
51 | {% include features/features-table.md %}
52 |
53 | ### Demo
54 |
55 | {% include preset/demo.md %}
56 |
57 | ### Storybook - UI components documentation
58 |
59 | Check out the [online Storybook documentation](https://nrn-v2-mst-aptd-gcms-lcz-sty-storybook.vercel.app/){:target="_blank"} for this preset.
60 |
61 | > Each preset has its own Storybook documentation, because a few components are different.
62 |
63 | ### Built-in 3rd party vendors
64 |
65 | {% include vendors/vendors-table.md %}
66 |
67 | ### Clone locally
68 |
69 | ```sh
70 | git clone https://github.com/UnlyEd/next-right-now.git nrn-{{preset}} && cd nrn-{{preset}} && git checkout {{preset}}
71 | ```
72 |
73 | This will create a `nrn-{{preset}}` folder in your current directory and checkout the `{{preset}}` git branch automatically.
74 |
75 | Cloning it once is enough, but it may be simpler to use one clone per preset if you're trying out multiple presets locally :wink:
76 |
77 | ### Local installation guide
78 |
79 | {% include installation-guide-full.md %}
80 |
81 | ### Advanced configuration
82 |
83 | {% include installation-guide-tips.md %}
84 |
--------------------------------------------------------------------------------
/concepts/analytics.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: Analytics
4 | parent: Concepts
5 | nav_order: 45
6 | ---
7 |
8 | # Analytics
9 |
10 |
11 | Analytics uses data and math to answer business questions, discover relationships, predict unknown outcomes and automate decisions. This diverse field of computer science is used to find meaningful patterns in data and uncover new knowledge based on applied mathematics, statistics, predictive modeling and machine learning techniques.
12 |
13 | No matter what you plan to accomplish with analytics, the first requirement for any analytics project is data. Once you have data, you need to analyze that data. And then you need to deploy the results of your analysis to drive decision making.
14 |
15 |
16 | [Source](https://www.sas.com/en_us/insights/analytics/what-is-analytics.html)
17 |
18 |
19 |
20 | ---
21 |
22 | Analytics is meant to allow you to collect and process metrics of the application.
23 |
24 | For instance, you may want to know how many people visited your homepage, or how many came back more than twice within the same month.
25 |
26 | Regarding analytics, it's as very important to:
27 | - Collect actionable data (focus on business KPIs)
28 | - Build comprehensive data analysis charts
29 | - Setup automated reports of your most important KPIs to help take important strategic decisions and initiatives
30 |
31 | Building a business without any analytics is similar to driving a car with your eyes closed.
32 |
33 | It is a pillar to any serious business website, and it is quite complicated to do it right. Tools matter!
34 |
35 | ---
36 |
37 |
12 | Simply put, CI/CD is a way of automating integration and deployment of source code changes, run various checks, and eventually deploy a newer version of the software, without requiring human interaction.
13 |
14 |
15 | {% include page-toc.md %}
16 |
17 | ---
18 |
19 | ## Introduction to CI/CD
20 |
21 | Continuous integration and continuous delivery are best practices for software development. Continuous integration is the software development practice of
22 | merging code changes into the project early and often. Instead of building out features in isolation and then integrating them at the end of a development
23 | cycle, code integrates with the shared repository multiple times throughout the day.
24 |
25 | ## Continuous Integration
26 |
27 | **Continuous Integration** grew out of a need to have developers working on features in parallel and on separate branches without fear of conflict. CI pipelines
28 | include automatic tools and processes (i.e. unit tests, linting tools) that automatically verify the code changes before merging it into the repository.
29 | Developers are less likely to be blocked by another developer’s work. CI results in changes that are easier to test and to revert. New work is introduced
30 | quickly in smaller bites. This also creates easier to review pull requests. These practices lead to a reduction in the time it takes to review PRs, find bugs
31 | and QA changes, while also maintaining the integrity and stability of the project.
32 |
33 | [Source](https://www.atlassian.com/continuous-delivery/continuous-integration)
34 |
35 | ## Continuous Deployment
36 |
37 | **Continuous Deployment** is a software release process that uses automated testing to validate if changes to a codebase are correct and stable for immediate
38 | autonomous deployment to a production environment. It ensures code changes are tested and ready for production deployment as soon as they are merged into the
39 | project. While the code does not have to be deployed to production, it should have been tested on a staging or a production environment. Our CI pipeline also
40 | includes automatic tools and processes (i.e. integration tests, end-to-end tests) that automatically test that the code is production-ready before releasing it
41 | to the repository.
42 |
43 | [Source](https://www.atlassian.com/continuous-delivery/continuous-deployment)
44 |
45 | ## GitHub Actions vendor
46 |
47 | We use GitHub Actions as our [CI/CD tools](../guides/ci-cd), and all our deployments are automated.
48 |
49 | ---
50 |
51 |
12 | NRN relies on environment variables to function correctly.
13 |
14 | Those variables are provided differently depending on the environment.
15 |
16 |
17 | {% include page-toc.md %}
18 |
19 | ---
20 |
21 | ## **Development** environment vs **Vercel** environment
22 | When working on the `development` environment (localhost), the variables from `.env.local` and then `.env` are used by [the webpack configuration](./next.config.js).
23 | _The variable defined in `.env.local` take precedence over those in `.env`, when they clash._
24 |
25 | When deploying an instance to the Vercel's platform, the variables used are the one that belong to the configuration file related to that instance, such as:
26 | - When running `yarn deploy:customer1`: This script will deploy an instance using the `vercel.customer1.staging.json` file.
27 | - When running `yarn deploy:customer1:production`: This script will deploy an instance using the `vercel.customer1.production.json` file.
28 |
29 | When pushing changes to the remote repository, it triggers a GitHub action.
30 | The action runs the `yarn deploy:*` script, and it works exactly the same as if you were running it from your local computer, except it's done on a CI server.
31 |
32 | > In those files, it's the `build.env` part that is used at build time (build is done on Vercel), which basically replaces all references of every environment variable by the actual value ("string replace", at build time).
33 |
34 | ---
35 |
36 | ## **Public** environment variables vs **private** env variables
37 | It can be very quick and easy to share some sensitive environment variable to the browser, usually by mistake.
38 |
39 | In order to make it obvious what variables are meant to be shared with the browser (and thus, to be public), [Next.js prefixes them with `NEXT_PUBLIC_`](https://nextjs.org/docs/basic-features/environment-variables#exposing-environment-variables-to-the-browser).
40 |
41 | **As a good practice**, we strongly recommend to only have public variables in your `.env` file. All non-public variables should be defined in `.env.local` instead.
42 |
43 | With this setup, it becomes clearer what's intended to be shared with the browser and what's actually private.
44 | And, what should be private shouldn't be tracked by Git either, and thus only defined in the local config file.
45 |
46 | > An exception to this rule is when an environment variable isn't public, but isn't sensitive either, and therefore conveniently stored in `.env` because it's just easier for collaboration.
47 |
48 | ---
49 |
50 | ## What is an **environment**?
51 |
52 | > An environment is "where" the application is running.
53 | > It can be either "development" (localhost) or "production" (on Vercel's servers).
54 | >
55 | > **The `environment` is defined by the `NODE_ENV` environment variable.**
56 | >
57 | > **Tip**: It is **not** possible to use any other value than `development` and `production`, [as enforced by Next](https://github.com/vercel/next.js/blob/master/errors/env-key-not-allowed.md)
58 |
59 | When working on your local computer, you automatically use `NODE_ENV=developement`.
60 |
61 | The environment affects how the application **is bundled**, it is defined at **build time**. (webpack, hot-reloading, etc.)
62 |
63 | > e.g: When building the app using the `development` environment, you have access to PropTypes warnings, but you won't when using `production`.
64 |
65 | ---
66 |
67 | ## What is a **stage**?
68 |
69 | > A stage is "how" the application is running.
70 | > It can be either "development" (localhost), "staging" or "production" (on Vercel's servers)
71 | >
72 | > _You can even add more stages, if you need_
73 | >
74 | > **The `stage` is defined by the `NEXT_PUBLIC_APP_STAGE` environment variable.**
75 | >
76 | > **Tip**: You can use any stage name you like, just make sure to use a slug (no space, no special chars, no accents, etc.).
77 |
78 | - When working on your local computer, NRN automatically uses `NEXT_PUBLIC_APP_STAGE=developement` _(as defined in `.env`)_.
79 | - When creating a Vercel preview deployment (e.g: when pushing a commit/branch (CD), or when using `yarn deploy`, etc.), NRN automatically uses `NEXT_PUBLIC_APP_STAGE=staging` _(as defined in `vercel.customer1.staging.json`)_.
80 | - When creating a Vercel production deployment (e.g: when using `yarn deploy:customer1:production`, or when merging a PR to the `master` or `main` branch, etc.), NRN automatically uses `NEXT_PUBLIC_APP_STAGE=production` _(as defined in `vercel.customer1.production.json`)_.
81 |
82 | The stage changes the behaviour of the application, because we sometimes need the application to behave differently depending on the stage.
83 |
84 | > The stage is **automatically selected** based on the `yarn deploy:*` script used.
85 | > (any push on **`master` or `main`** is considered as **production** stage, while any push on **any other branch** is considered as **staging** stage)
86 |
87 | > e.g: In `production` stage, the Locize configuration uses the `production` version.
88 | > When using another stage, it uses the `latest` version.
89 |
90 | > e.g: We don't want to enable the same level of debugging in production environment.
91 | > For instance, Locize is configured to be in `debug` mode only in non-production stages.
92 |
93 | ---
94 |
95 |
12 | GraphQL is a query language for your API, and a server-side runtime for executing queries by using a type system you define for your data. GraphQL isn't tied to any specific database or storage engine and is instead backed by your existing code and data.
13 |
14 |
15 | [Source](https://graphql.org/learn/)
16 |
17 |
18 |
19 | {% include page-toc.md %}
20 |
21 | ---
22 |
23 | ## Usage of GraphQL with Next Right Now
24 |
25 | GraphQL is used by all presets including `gcms` in their name. (i.e: [`v2-mst-aptd-gcms-lcz-sty`](../available-presets/v2-mst-aptd-gcms-lcz-sty))
26 |
27 | ## Why GraphQL over REST?
28 |
29 | > If you want to learn about the pros/cons of GraphQL vs other API protocols, we suggest reading [Comparing API Architectural Styles: SOAP vs REST vs GraphQL vs RPC](https://levelup.gitconnected.com/comparing-api-architectural-styles-soap-vs-rest-vs-graphql-vs-rpc-84a3720adefa)
30 |
31 | Some issues of the REST API are:
32 | - We often call multiple endpoints to fetch the data required for one page, screen or for a particular component tree.
33 | - Airtable API (REST-ish) is a good example. You need to send 30 HTTP request to fetch the data from 30 different tables, but you only need one request when using GraphQL.
34 | - The data returned is non-negotiable. We cannot opt to not receive certain return values unless we explicitly code it in the route handling logic. This will in turn introduce more complexity to the request body.
35 | - Or you won't have the option implemented, at all. And it depends on the API implementation, all REST APIs are implemented differently and very few have a solid foundation.
36 | - If an endpoint is updated with a different response value, all installed apps or front-end clients will also need to be updated to handle that change. To overcome this, versioning has become a standard practice with RESTful APIs, along with managing deprecation for an entire API version, rather than just particular endpoints.
37 | - Although global validation mechanisms such as authentication can be handled through middleware, validating request bodies on a per-endpoint basis is often repetitive and introduces more boilerplate code.
38 |
39 | ## Want more?
40 |
41 | If you're not familiar with the differences between REST and GraphQL:
42 | - [https://goodapi.co/blog/rest-vs-graphql](https://goodapi.co/blog/rest-vs-graphql)
43 | - [https://medium.com/@rossbulat/graphql-in-javascript-an-introduction-f50b8dc6e92](https://medium.com/@rossbulat/graphql-in-javascript-an-introduction-f50b8dc6e92)
44 |
45 | - **Tip**: Make sur to check the official [GraphQL tutorial](https://graphql.org/learn/) if you want to learn more about it!
46 | - You should probably focus on the "client" usage, and use a Headless CMS that manages the server for you, it's much less work! :wink:
47 |
48 | ---
49 |
50 |
12 | **Internationalization**, often abbreviated as i18n, is the process through which products can be prepared to be taken to other countries.
13 | It doesn’t just mean being able to change languages.
14 | Instead, it means being able to accept different forms of data, different settings to match local customs and different strings of data and process it correctly.
15 |
16 | **Localization** (l10n) is simply the act of changing a piece of software to suit a different locale.
17 |
18 | In many ways, internationalization can be thought of as building the structure of a piece of software so that it can be adjusted for different markets,
19 | and localization is the process of actually doing so for a specific market.
20 |
21 |
22 | [Source](https://phrase.com/blog/posts/i18n-a-simple-definition/)
23 |
24 |
25 |
26 | {% include page-toc.md %}
27 |
28 | ---
29 |
30 | ## Understanding the differences between "Dynamic" and "Static" i18n
31 |
32 | We will only mention i18n with NRN, not l10n.
33 | Both are very similar and can be grouped together as i18n, because l10n relies on i18n capabilities.
34 |
35 | The content displayed on NRN is translated using different ways, depending on where the translations are stored:
36 | 1. **Dynamic** i18n - Content-related (e.g: Post title in FR + EN). It will depend on your data and how you fetch those data (real-time SSR, SSG, etc.)
37 | 1. **Static** i18n - Everything that isn't related to dynamic content (e.g: Site links, any static content not related to dynamic data).
38 | It will depend on how you fetch those data (vendor (API), i18n static files, etc.)
39 |
40 | It is possible, although very rare, to use the same system/vendor for both "dynamic" and "static" i18n.
41 |
42 | For instance, one could imagine storing all its static content within it's dynamic i18n content.
43 |
44 | This design would have a few pros/cons:
45 | - Content would be available online (CMS/back office) and may be updated by non-IT teams
46 | - Content would need to be fetched for each request (when using SSR), but that could be mitigated by using SSG
47 | - For example, replacing Locize by GraphCMS would allow storing all content at the same place, but would lack i18n-specific features offered by Locize.
48 |
49 | ---
50 |
51 | ## A few words on "static i18n"
52 |
53 | I18n with Next.js isn't an easy topic, and many smart people have tried to provide a solution about it.
54 |
55 | Unfortunately, there are no magic solution out there.
56 | - [Next.js thread about i18n](https://github.com/vercel/next.js/discussions/10651)
57 | - [`next-i18next` isn't compatible with the Next.js 9.3+ version](https://github.com/isaachinman/next-i18next/issues/274)
58 | - It requires an additional Express server, there are extra complication due to the Serverless nature of Next.js apps (no proper local storage)
59 | - [The official next example relies on a `_pages` hack folder](https://github.com/vercel/next.js/tree/canary/examples/with-next-translate)
60 | - Feels hacky, and I've got no idea what drawbacks this could create in the future, as it's not the way the `pages` folder is meant to be used
61 |
62 | ### How we do
63 |
64 | Our way works with SSG and SSR.
65 | We strongly recommend using SSG whenever possible, because it'll increase the speed of pages rendering, reduce costs, and more.
66 |
67 | Using SSG, we fetch i18n content at build time and generate static pages.
68 | This avoids over-fetching your i18n provider for each end-user request, and remove this vendor from the potential list of threats of your app.
69 | (even if your vendor API goes down, it won't affect your end-users because you only use its API at build time)
70 |
71 | Such design also has various benefits and limitations.
72 | For example, you can't change static content without rebuilding your app, but it also increases the speed of your pages because you don't have to fetch static content anymore.
73 |
74 | Using SSR, we fetch i18n content for every end-user request, in real time.
75 | Of course, there are a few optimisations, such as browser/server caching, but they're not as efficient as statically generated pages.
76 |
77 | ---
78 |
79 | ## A few words on "dynamic i18n"
80 |
81 | **Dynamic i18n** is a bit easier in our opinion.
82 | If you need those data dynamically, then you'll have to use your vendor API to fetch the i18n content, the same way you're using its API to fetch non-i18n data.
83 |
84 | SSG is becoming very attractive in 2020, and most sites **don't actually need to perform real-time requests** to fetch up-to-date content.
85 | But, that's quite a change of thinking/designing web apps, and it may not fit your business requirements.
86 |
87 | We recommend to use SSG whenever possible, and build your static pages at build time.
88 | If you need to rebuild your pages based on CMS changes and such, you should take a look at the newer [incremental static regeneration](https://nextjs.org/blog/next-9-4#incremental-static-regeneration-beta) feature.
89 |
90 | There is no bullet-proof-fit-them-all solution on this, it depends on your requirements and limitations.
91 |
92 | ---
93 |
94 | ## Personal note
95 |
96 | Our personal advice on this is to keep an eye on the [RFC: Incremental Static Regeneration](https://github.com/vercel/next.js/discussions/11552)
97 | because it should soon yield some very interesting and powerful features to help us keep our statically generated apps up-to-date based on complex workflows.
98 |
99 | > Keep in mind that **i18n depends on how your render your app**, and this has many, complex implications. (SSR, SSG, etc.)
100 |
101 | ---
102 |
103 |
13 | This section explains the different concepts around Next Right Now.
14 |
15 | We recommend to follow the given order to go through them all.
16 |
17 | You don't have to read/understand all of them, pick those that seem related to your needs.
18 |
19 | > We strongly recommend reading both **Presets** and **Environments and Stages**, because they're both pillars of NRN and will be necessary anyway.
20 |
12 | Website monitoring is the process of testing and logging the status and uptime performance of one or more websites. This monitoring tool ensures that websites are accessible for all users and is used by businesses and organizations to ensure that website uptime, functionality and performance are always up to standard.
13 |
14 |
15 | [Source](https://www.techopedia.com/definition/29994/website-monitoring)
16 |
17 |
18 |
19 | ---
20 |
21 | Monitoring is a must-have in any production-grade application. How can fix a problem if you're not even aware of its existence?
22 |
23 | Monitoring can focus on the server side, or on the client side. But because NRN is an isomorphic application, it focuses on both.
24 |
25 | A good monitoring tool should automatically report any uncaught exception in your source code, so that nothing gets under your radar.
26 | Also, it should allow you to pipe those reports to collaboration tools such as Slack, so that all the team gets alerted when something bad happens.
27 |
28 | Additionally, it should include as much contextual data as possible, to help you understand and debug what actually happened.
29 |
30 | Monitoring is so important, you can't afford to get it wrong. Tools matter!
31 |
32 | ---
33 |
34 |
12 | Unit tests and end-to-end (E2E) tests workflow.
13 |
14 |
15 | {% include page-toc.md %}
16 |
17 | ---
18 |
19 | ## CI tests Workflow
20 |
21 | Vercel will automatically run the tests before deploying, as configured in the `yarn build` command.
22 |
23 | > If any test fail, the deployment will be aborted. This ensures that any code that doesn't pass the tests never get deployed online.
24 |
25 | Once a deployment has been deployed on Vercel, **Github Actions** will run our **E2E tests**, to make sure that the app behaves as expected.
26 | This can also be considered as an integration tests suite.
27 |
28 | ## Running tests manually (locally)
29 | You can run interactive tests using Jest with `yarn test` script.
30 |
31 | ## Running E2E tests manually (locally)
32 | You can run interactive E2E tests using Cypress with `yarn e2e:open` script.
33 |
34 | You can also run them non-interactively using `yarn e2e:run` script.
35 |
36 | > You may need to run `yarn e2e:install` script first
37 |
38 | ---
39 |
40 |
51 |
--------------------------------------------------------------------------------
/contributing.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: CONTRIBUTING
4 | nav_order: 90
5 | ---
6 |
7 | # Contributing
8 | {: .no_toc }
9 |
10 | {% include page-toc.md %}
11 |
12 | ---
13 |
14 | ## Contributing about documentation
15 |
16 | Our documentation lives in the `docs/` folder. It is generated and hosted on Github Pages.
17 |
18 | Only the [`gh-pages`](https://github.com/UnlyEd/next-right-now/tree/gh-pages) branch generates the online documentation. (it's our default branch)
19 |
20 | It uses [Jekyll](https://jekyllrb.com/) behind the wheel, and [`just-the-docs`](https://pmarsceill.github.io/just-the-docs/) theme for Jekyll.
21 |
22 | ---
23 |
24 | ### Installing Jekyll locally
25 |
26 | In order to contribute to the docs, you may need to install Jekyll locally (especially for non-trivial changes).
27 | Jekyll needs Ruby binary.
28 |
29 | 1. Install and configure Jekyll on your computer, follow [https://jekyllrb.com/docs/](https://jekyllrb.com/docs/)
30 | 1. Once Jekyll is installed, you can install all Ruby gems using `yarn doc:gem:install`
31 | 1. Once gems are installed, you can run the local Jekyll server by using `yarn doc:start` which will start the server at localhost:4000
32 |
33 | ---
34 |
35 | ### Configuring Jekyll properly
36 |
37 | Jekyll configuration uses 2 different files.
38 | - [`docs/_config.yml`](docs/_config.yml) used by Github Pages
39 | - [`docs/_config-development.yml`](docs/_config-development.yml) used by your local installation
40 |
41 | There are a few, but important differences between both. The custom configuration must be written at the top of each config file.
42 | The shared configuration must be written below.
43 |
44 | > **Tip**: If you add custom/shared configuration, don't forget to update both config files, as needed.
45 |
46 | ---
47 |
48 | ### Reference
49 |
50 | Jekyll theme used: [`just-the-docs`](https://pmarsceill.github.io/just-the-docs/)
51 |
52 | #### How to build a custom TOC
53 |
54 | See [just-the-docs documentation](https://pmarsceill.github.io/just-the-docs/docs/navigation-structure/#in-page-navigation-with-table-of-contents)
55 |
56 | #### How to write comments in Markdown files
57 |
58 | ```md
59 | [//]: # (Some markdown comment)
60 | ```
61 |
62 | ---
63 |
64 | ### Known issues
65 |
66 | - Using `yarn doc:start` will rebuild the whole documentation, but it's slower. Using `yarn doc:start:fast` won't rebuild the whole thing, and it's faster.
67 | If you're working on the navigation menu, be warned the fast mode won't apply changes, and your menu links won't update.
68 |
69 | ---
70 |
71 | ## Contributing about the source code
72 |
73 | If you mean to contribute on any preset by adding a new feature, or update existing ones, etc. please see our [open RFC about contributing](https://github.com/UnlyEd/next-right-now/issues/57).
74 |
75 | Please open an issue first before contributing, so that we may discuss your contribution beforehand.
76 | This isn't necessary for small changes, but non-trivial changes should be agreed upon first.
77 |
78 | Also, if you provide a PR, please [configure CI on your GitHub repository](./guides/ci-cd/gha-deploy-vercel) first, otherwise we'll need to "fork" your PR into NRN to test it first, and that takes time.
79 |
80 | Additionally, please allow us to update your PR's code for easier collaboration.
81 |
82 | ## Requesting a new Preset
83 |
84 | If you need a preset that isn't supported yet, you can request one through [Github issues](https://github.com/UnlyEd/next-right-now/issues/new).
85 |
86 | - Please check first if there isn't an **existing request**, you can use the [Github label `"request preset"`](https://github.com/UnlyEd/next-right-now/issues?q=is%3Aopen+is%3Aissue+label%3A%22request+preset%22) to filter them out.
87 | - Please check first which presets [**won't be worked on by the NRN team**](./concepts/presets.html#which-presets-arent-being-considered) and must come from contributions.
88 |
89 | ---
90 |
91 |
102 |
--------------------------------------------------------------------------------
/faq.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: FAQ
4 | nav_order: 70
5 | ---
6 |
7 | # FAQ
8 | {: .no_toc }
9 |
10 | {% include page-toc.md %}
11 |
12 | ---
13 |
14 | ## Where can I see a change log of what's changed in Next Right Now?
15 |
16 | We provide a [CHANGELOG](./changelog) listing our most important changes. They're also released in our [Community Discussion](https://github.com/UnlyEd/next-right-now/discussions/166).
17 |
18 | Additionally, as of December 2020, you can see [all releases](https://github.com/UnlyEd/next-right-now/releases) that are automatically created and describe changes, per preset.
19 |
20 | ---
21 |
22 | ## How can I subscribe to changes made to Next Right Now, to be notified in the future?
23 |
24 | [Subscribe to the discussion](https://github.com/UnlyEd/next-right-now/discussions/166) to be notified when new releases are made, and participate in the
25 | discussion about what has changed!
26 |
27 | ---
28 |
29 |
30 | ## Can I use NRN on Windows?
31 |
32 | {% include windows-concerns.md %}
33 |
34 | [See original question](https://github.com/UnlyEd/next-right-now/issues/55)
35 |
36 | ---
37 |
38 | ## I try to deploy locally, but I get "The specified scope does not exist"
39 |
40 | ```
41 | $ npx vercel
42 | Vercel CLI 20.1.4
43 | Error! The specified scope does not exist
44 | > More details: https://err.sh/vercel/scope-not-existent
45 | ```
46 |
47 | **This is because you're using NRN own `scope` in your `vercel.*.json` files.**
48 |
49 | 1. Remove the whole line `"scope": "team_qnVfSEVc2WwmOE1OYhZr4VST",` in all `vercel.*.json` files.
50 | - **Tip**: Don't forget `vercel.json` is a **symlink** and **shouldn't** to be modified (run `ln vercel.staging.json vercel.json` if you messed it up :wink:)
51 |
52 | ---
53 |
54 | ## How is the `i18nextInstance` passed to react?
55 |
56 |
57 | **Question**: _I wanted to understand how the i18next integration works. How is the `i18nextInstance` passed to react? It seems to be passed to the `Layout` component, but the `Layout` component never uses it. So how does this work?_
58 |
59 |
60 | - The `i18nextInstance` isn't necessary to perform translations actually, it's forwarded as a utility.
61 | - Manipulating the `i18nextInstance` is not necessary, using `import { Trans, useTranslation } from 'react-i18next';` is what you'll need most of the time when translating content.
62 | - The `i18next` library is actually initiated in `i18nextLocize.ts`
63 |
64 | [See original question](https://github.com/UnlyEd/next-right-now/issues/14#issuecomment-601557549)
65 |
66 | ---
67 |
68 | ## Should I be keeping the `MST` tenancy design even though I don't have use for it?
69 |
70 |
71 | **Question**: _I don't find the "plugin" system that highly customizable since "plugins" seem to already be bundled into the 2 main templates you offer, and I have been having hard time trying to rip things out that I don't need (i18n/locize, example app, MST tenancy (although looks like I can opt out by not using certain vercel json files), and etc.)._
72 |
73 |
74 | See our guide about ["How to remove MST"](./guides/tenancy/remove-MST).
75 |
76 | [See original question](https://github.com/UnlyEd/next-right-now/issues/151)
77 |
78 | ---
79 |
80 | ## How do I remove plugins/features I do not want?
81 |
82 |
83 | **Question**: _I don't find the "plugin" system that highly customizable since "plugins" seem to already be bundled into the 2 main templates you offer, and I have been having hard time trying to rip things out that I don't need (i18n/locize, example app, MST tenancy, etc.)._
84 |
85 |
86 | See our ["How to remove X" guides](./guides). **Each tool has its own "How to remove" section.**
87 |
88 | If you don't find what you're looking for, you can open a discussion/issue on github.
89 |
90 | > Please contribute to the documentation if you manage to remove something that isn't properly documented! :blush:
91 |
92 | [See original question](https://github.com/UnlyEd/next-right-now/issues/151)
93 |
94 | ---
95 |
96 | ## What is `MultiversalAppBootstrap`?
97 |
98 |
99 | **Question**: _I would like to understand the purpose of this component `MultiversalAppBootstrap.tsx` and its siblings components `BrowserPageBootstrap.tsx`, `ServerPageBootstrap.tsx` and `UniversalGlobalStyles.tsx`, I may have missed something in the documentation. But I don't understand its usefulness knowing that we have `_app` and `_document`... are to separate the logic of each type of rendering, or only for maintainability purposes?_
100 |
101 |
102 | See the [Application Bootstrap concept](./concepts/app-bootstrap).
103 |
104 | If you don't find what you're looking for, you can open a discussion/issue on github.
105 |
106 | ---
107 |
108 | ## What's the NRN page lifecycle?
109 |
110 | See the [Application Bootstrap page lifecycle](./concepts/app-bootstrap#whats-the-nrn-page-lifecycle).
111 |
112 | ---
113 |
114 | ## There are a lot of scripts in the `package.json` file, are they documented?
115 |
116 | See the [scripts documentation](./guides/scripts-and-utilities/#scripts), where all commands are thoroughly explained.
117 |
118 | ---
119 |
120 |
12 | This section contains everything about how to get started with Next Right Now, as a boilerplate for your own project.
13 |
14 |
15 | ---
16 |
17 | Here is the order we recommend:
18 |
19 | 1. [Pre-requisites](./pre-requisites): Make sure all required tools are installed.
20 | 1. [Quick start](./quick-start): Quickly get started with a preset and run it on your own computer under 5mn.
21 | 1. [Video tutorials](./video-tutorials): Check our video tutorial to get an overview of what using NRN really looks like, from a developer point of view. _(Early 2020, `v1`, outdated)_
22 |
23 | ## Want more?
24 |
25 | - [Folder structure](../reference/folder-structure): Understand the boilerplate folder structure in a breeze.
26 | - [Demo DB structure](../reference/demo-database-structure): Understand the database structure used for the demo (Airtable, GraphCMS).
27 | - [Vendors pricing](../reference/vendors): Overview of the vendors pricing and what you should be aware of.
28 |
29 | ## Want some real fun?
30 |
31 | - [Dependencies documentation](../reference/dependencies): Overview of NRN dependencies.
32 |
33 | ---
34 |
35 |
46 |
--------------------------------------------------------------------------------
/getting-started/pre-requisites.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: Pre-requisites
4 | parent: Getting started
5 | nav_order: 15
6 | ---
7 |
8 | # Pre-requisites
9 |
10 | ---
11 |
12 | NRN expects the following to be already installed on your computer:
13 |
14 | - [Git](https://git-scm.com/downloads) will be necessary to clone the repository on your computer.
15 | - _(Optional)_ A proper Node Version Manager (NVM) to manage installed Nodejs versions (allows switching between versions)
16 | - It's not really a requirement, but a good practice for any developer working on multiple projects (which eventually leads to working on different nodejs versions).
17 | - [NVM for Unix](https://github.com/nvm-sh/nvm) (run the [install script](https://github.com/nvm-sh/nvm#install--update-script))
18 | - [NVM for Windows](https://github.com/coreybutler/nvm-windows) (download the [latest `nvm-setup.zip`](https://github.com/coreybutler/nvm-windows/releases))
19 | - **If you don't use NVM**, then please use node `v12` for the next steps. [Because that's what's used by Vercel hosting](../guides/online-hosting/use-vercel)
20 | - Node.js should be installed (it's installed by NVM, so you're probably already covered)
21 | - _(Optional)_ [Yarn](https://classic.yarnpkg.com/en/docs/install/) is preferred over NPM, for various reasons. All our example use Yarn, but you can theoretically use either.
22 |
23 | As you can see, there is no particular dependency to use NRN, all those tools are probably already installed on your computer!
24 |
25 | _Note that Cypress will require additional binaries, but it's not a requirement, and we'll cover that part later._
26 |
27 | ## Operating systems compatibility
28 |
29 | ### Unix (MacOS/Linux distributions)
30 |
31 | NRN has only been extensively tested on **MacOS Catalina**, we expect **Unix-based OS** to behave properly.
32 |
33 | ### Windows
34 |
35 | NRN v2 has been tested on Windows (on June 1st, 2020) and works correctly.
36 |
37 | Tested on Windows 8 (using Babun and WebStorm) and Windows 10 (using VSCode).
38 |
39 | [Read our FAQ](../faq#can-i-use-nrn-on-windows)
40 |
41 | ---
42 |
43 |
14 |
15 | {% include page-toc.md %}
16 |
17 | ---
18 |
19 | This short tutorial will explain how to perform a super quick (~5mn) local installation (for local-only testing purpose, without deploying anything online)
20 |
21 | This tutorial uses the [**`{{ site.nrn_default_preset }}`**](../available-presets) preset.
22 |
23 | > It doesn't really matter if the selected preset fits your needs, the goal here is to give you a tour of what NRN can do for you, as quickly as possible.
24 |
25 | ## Step-by-step installation
26 |
27 | {% include installation-guide-quick-start.md preset=site.nrn_default_preset %}
28 |
29 | ---
30 |
31 |
32 | :books: **Recommended**: Go through the Concepts section:
33 |
34 | Learn more about NRN concepts before getting your hands dirty :wink:
35 |
52 | :rocket: **For experimented developers** - _or if you're in a hurry_:
53 |
54 | Pick the Preset that best fit your needs and it deploy online right now!
55 |
12 | Those videos will show you how NRN works, from a developer point of view.
13 |
14 | They're great to watch if you want a peek preview of all available features and how they work.
15 |
16 | **Note that video tutorial were recording during NRN v1. They've been recorded in early 2020 and are outdated.**
17 |
18 | The Next Right Now demos have been improved a lot since, and more features have been added.
19 |
20 |
21 | {% include page-toc.md %}
22 |
23 | ---
24 |
25 | ## Part 1 - Overview of Next Right Now (15 minutes)
26 | [](http://youtu.be/kltkFwnFL-k?hd=1)
27 |
28 | Let's talk about why we built RNR in the first place, how it's meant to be used and who it's for.
29 |
30 | > This video features Vercel deployments, i18n, GraphCMS, Locize in-context editor, Sentry monitoring, Amplitude analytics, CI/CD Github Actions
31 |
32 | ## Part 2 - Developer Experience with Next Right Now (15 minutes)
33 | [](http://youtu.be/fGlgIEeUqFg?hd=1)
34 |
35 | Let's talk about the developer experience (DX) provided by NRN and how it helps being more efficient.
36 |
37 | > This video features GraphQL auto-completion and local schema update, deployment workflow, CI/CD Github Actions explanations, interactive E2E testing, GraphsCMS field creation
38 |
39 | ---
40 |
41 |
10 |
11 | Orchestrate powerful business solutions with a single source of truth. The only limit is your imagination.
12 |
13 |
14 |
15 | ---
16 |
17 | # About Airtable
18 |
19 | [Learn more](https://airtable.com/)
20 |
21 | ## Airtable (REST-ish) vs other API protocols
22 |
23 | > If you want to learn about the pros/cons of Airtable API vs other API protocols, we suggest reading [Comparing API Architectural Styles: SOAP vs REST vs GraphQL vs RPC](https://levelup.gitconnected.com/comparing-api-architectural-styles-soap-vs-rest-vs-graphql-vs-rpc-84a3720adefa)
24 |
25 | Note Airtable uses a REST-ish API.
26 |
27 | ## Airtable and Next Right Now
28 |
29 | Next Right Now provides various presets. Some of those presets include a built-in Airtable support.
30 |
31 | In particular, the preset `v2-mst-aptd-at-lcz-sty` includes Airtable support. _(`at`)_
32 |
--------------------------------------------------------------------------------
/guides/airtable-api/setup-airtable.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: How to setup Airtable
4 | parent: Airtable API
5 | grand_parent: Guides
6 | nav_order: 10
7 | ---
8 |
9 | # How to setup Airtable
10 | {: .no_toc }
11 |
12 |
13 | Step-by-step guide about how to create and properly configure your Airtable account.
14 |
15 |
16 | {% include page-toc.md %}
17 |
18 | ---
19 |
20 | ## Create Airtable account
21 |
22 | - [Create a free account on Airtable](https://airtable.com/signup/?ref=unly-nrn)
23 | - [Create a new base based on the base we used](https://airtable.com/shrnxN46JDBkQV9u1)
24 | - You can simply clone the base if you wish to make it your own (top right)
25 |
26 | ---
27 |
28 | ## Learn how to configure your Airtable base
29 |
30 | #### API token
31 |
32 | Be extra careful about the Airtable API token, it's the same token shared for all your bases within your Airtable account.
33 | If it gets leaked, it might cause the leak of all your bases.
34 |
35 | > When I created this NRN demo with Airtable, I created a whole different account so that it wouldn't affect our company business in any way.
36 |
37 | You can find your API token by going on any `Base > Help > API documentation > Check "Show API key"` and scroll to the "Authentication" section.
38 |
39 | ---
40 |
41 | ## Configure Airtable credentials
42 |
43 | You need to set `AIRTABLE_BASE_ID` and `AIRTABLE_API_KEY` in your `.env.local` file to work locally.
44 |
45 | You'll also need to add those values as Vercel secrets.
46 |
47 | Example: `vercel secrets add nrn-airtable-api-key your-key`
48 |
49 | ---
50 |
51 |
52 |
53 | [How to use GraphCMS >](./use-graphcms){: .btn .btn-purple }
54 |
55 |
56 |
--------------------------------------------------------------------------------
/guides/airtable-api/use-airtable.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: How to use Airtable
4 | parent: Airtable API
5 | grand_parent: Guides
6 | nav_order: 20
7 | ---
8 |
9 | # How to use Airtable
10 | {: .no_toc }
11 |
12 |
13 | Advices and "must-know" things regarding Airtable usage.
14 |
15 |
16 | {% include page-toc.md %}
17 |
18 | ---
19 |
20 | ## Overview
21 |
22 | [Getting started](https://support.airtable.com/hc/en-us/sections/360003922433)
23 |
24 | Airtable is very similar to Excel and Google Sheets. It's more user-friendly than both, but not as powerful sometimes.
25 |
26 | We love it for many reasons, even though their API is not great and feels like it's been designed by a bunch of junior developers.
27 | But maybe that explains why their API is still in `v0` even though it was founded in 2012?
28 |
29 | ## Assets (AKA "Attachments")
30 |
31 | Airtable attachments access cannot be secured as they cannot be password-protected.
32 | This is a must-know if you're thinking about storing some assets (images, documents) in Airtable.
33 |
34 | If you're thinking about storing sensitive documents, then we strongly suggest you use another provider to store those assets, even though you might store their URL in Airtable itself, with confidence.
35 |
36 | Also, attachments don't expire. Once an asset has been uploaded in Airtable, there is no way for you to remove it for real. While you can remove it from your base itself, the asset will still live online "forever".
37 | You might get the Airtable support to remove such asset for you, on a case-by-case basis. We've never tried though.
38 |
39 | ## Custom "Apps" (previously "Blocks")
40 |
41 | Airtable allows you to create your own Apps. We recently created a custom app [`airtable-print-base-schema`](https://github.com/UnlyEd/airtable-print-base-schema).
42 | We're in the process of releasing it as an official app, but it's slow as it goes through a manual process. (been more than 2 months, and still not done due to multiple feedback and change requests from the Airtable team)
43 |
44 | Apps are a great way to build your own mini-apps within Airtable, and can be powerful tools for your team.
45 |
46 | Your app doesn't need to be officially allowed for you to use it your own Base, but it definitely makes it easier for other people to install it.
47 |
48 | ## Known limitations
49 |
50 | One of the most frustrating things with Airtable is their API. It suffers from so many limitations, it makes it hardly reliable for many use-cases.
51 |
52 | - **API rate limit**: There are some rates limit to the API.
53 | Officially, it's 5 requests/second. Unofficially, they increased it to around 20-30 requests/second due to customer complaints.
54 | You can't really know when you'll reach the limit, there is no header or such that might help you foreseen reaching the limit. It'll simply respond with some 429 error code when reached.
55 | This design is bad for us, in particular because we send many requests when building our SSG pages.
56 | And, because their API is REST-ish, it only supports fetching one "table" at once, meaning you must send 1 request for each table.
57 | - **No webhook**: There is no native/simple way to be notified about a change in the data, there is no WebHook support.
58 | This limitation might be overcome using a custom App that acts as a listener and call your own server upon detecting changes.
59 | - **No way to retrieve table/fields metadata**: The API only allows to interact with resources, not with the database schema.
60 | - **Backups can be complicated**: Due to the lack of support for reading the database schema, it's very hard to efficiently save the whole database.
61 | [I've written extensively about that after studying about 10 different backups and restoration strategies](https://community.airtable.com/t/state-of-airtable-backup-restoration-2020-summary-of-existing-tools/36124).
62 |
--------------------------------------------------------------------------------
/guides/analytics/index.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: Analytics
4 | parent: Guides
5 | nav_order: 40
6 | has_children: true
7 | ---
8 |
9 | # Amplitude provider
10 |
11 | We decided from the beginning to use Amplitude instead of the traditional Google Analytics.
12 |
13 | This choice was motivated by our experience with Google Analytics, which is not a good tool when building dynamic apps.
14 | As GA was created in 2005, when the web was all about full page reload, it was not designed to handle apps with dynamic parts.
15 |
16 | While it works really great with simple page transitions (full page reload), it provides a very bad experience for developers.
17 | Also, their "real-time" feature and overall developer experience is really poor.
18 |
19 | On the other hand, Amplitude provides great features and makes it very easy to integrate to Next.js using a community-powered React library.
20 |
--------------------------------------------------------------------------------
/guides/analytics/remove-amplitude.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: How to remove Amplitude
4 | parent: Analytics
5 | grand_parent: Guides
6 | nav_order: 30
7 | ---
8 |
9 | # How to remove Amplitude
10 |
11 | ---
12 |
13 | 1. Remove the following libraries:
14 | - [`amplitude-js`](https://www.npmjs.com/package/amplitude-js): Top-level amplitude official lib, used by react-amplitude.
15 | - [`@amplitude/react-amplitude`](https://www.npmjs.com/package/react-amplitude): React-friendly amplitude lib, non-officially maintained. Really useful when working with react.
16 |
17 | 1. Remove their components usage in the source code
18 | 1. Remove the `NEXT_PUBLIC_AMPLITUDE_API_KEY` env var, in `.env`
19 |
--------------------------------------------------------------------------------
/guides/analytics/setup-amplitude.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: How to setup Amplitude
4 | parent: Analytics
5 | grand_parent: Guides
6 | nav_order: 10
7 | ---
8 |
9 | # How to setup Amplitude
10 | {: .no_toc }
11 |
12 |
13 | Guide about how to properly configure Amplitude.
14 |
15 |
16 | {% include page-toc.md %}
17 |
18 | ---
19 |
20 | ## Create an Amplitude account
21 |
22 | 1. Go to [https://amplitude.com/](https://amplitude.com/?ref=unly-nrn) and check their online demo to familiarise you a bit with the features and UI.
23 | 1. [Create an account](https://amplitude.com/signup?ref=unly-nrn)
24 | 1. Create a "[NRN] Staging" project. We recommend to use a different project per stage.
25 | - We usually have one "Production" and one "Stating" versions, the staging version stores both development and staging events in order to keep the production database clean
26 | 1. Create a "[NRN] Production" project
27 | 1. Once your projects are created, go to "Manage data" (bottom left)
28 | 1. Select your project
29 | 1. Go to "Project settings"
30 | 1. Copy the "API Key" value (not the secret!) and apply it to `NEXT_PUBLIC_AMPLITUDE_API_KEY` in `.env`
31 | 1. If you have already configured Vercel, and if you want to deploy your app online, you must also configure Vercel secrets
32 | - `vercel secrets add nrn-amplitude-api-key-staging YOUR_AMPLITUDE_STAGING_API_KEY`
33 | - (Optional) Get your "[NRN] Production" "API key" too, and run `vercel secrets add nrn-amplitude-api-key-production YOUR_AMPLITUDE_PRODUCTION_API_KEY`
34 | - This is only useful if you attempt to deploy to production
35 |
36 | That's it! Your Amplitude account is ready to use!
37 |
--------------------------------------------------------------------------------
/guides/analytics/use-amplitude.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: How to use Amplitude
4 | parent: Analytics
5 | grand_parent: Guides
6 | nav_order: 20
7 | ---
8 |
9 | # How to use Amplitude
10 | {: .no_toc }
11 |
12 |
13 | Advices and "must-know" things regarding Amplitude usage.
14 |
15 |
16 | {% include page-toc.md %}
17 |
18 | ---
19 |
20 | ## Overview
21 |
22 | ### A few words about Amplitude vs Google Analytics
23 |
24 | When your want to perform Analytics in any app, people usually go for Google Analytics. **We don't.**
25 |
26 | GA is too limited, and huge, with tons of useless stuff.
27 | We've used it, and we really don't recommend it for any SPA, especially when playing with universal app because it just sucks.
28 |
29 | > It's very hard to configure GA with universal apps, you'll end up with wrong analytics insights due to event multi triggers (SSR + CSR).
30 | > It was designed and built for another world. **Not for SPA or CSR!**
31 | >
32 | > - _Our opinion_
33 |
34 | Instead, we use (and recommend) Amplitude.
35 | The world of analytics is huge, and isn't cheap.
36 |
37 | Amplitude allows tracking events and users behaviour, who are two very different things, even if events are related to users.
38 |
39 | It's simply the best one we've worked with since 2018.
40 |
41 | It's much more flexible than Google Analytics. Also, it plays much better with isomorphic apps and SPA.
42 |
43 | If you want fine-grained control over the data you want to collect, it's the perfect tool for the job.
44 |
45 | Also, it provides a really great react package.
46 |
47 | [Read our vendors review](../reference/vendors).
48 |
49 | ### A note about Amplitude's pricing
50 |
51 | Amplitude [offers a free plan](https://amplitude.com/pricing) that allows 10 million events per months (`$identity` events aren't counted towards `events`, they're free).
52 |
53 | Then, the cheapest plan is `Growth`, that **starts around $48k/year** (yup, it's a **huge** gap)
54 |
55 | If you want to benefit from the **Growth plan for free**, know that it's possible (but limited to 1 years), through their [startup Scholarship](https://amplitude.com/startups).
56 | **They offer Scholarship for non-profit organisation too.**
57 |
58 | > But, a word of caution here, even if you benefit from the scholarship, make sure your business doesn't rely on Growth features when your Scholarship ends.
59 | >
60 | > They told us then always find a way to provide Amplitude at an acceptable price for non-profit, but we don't know that for sure yet.
61 |
62 | Anyway, Amplitude is [one of the best out there for Analytics](https://stackshare.io/amplitude).
63 |
64 | If the free plan is enough for your needs, or if you can afford paid plans then don't hesitate.
65 | Also, their react integration is really good, even though it's not officially maintained and could use some love. (they told us they plan of maintaining it better)
66 |
67 |
68 | ### Known limitations
69 |
70 | - ~~Amplitude doesn't provide any backend-compatible API.~~
71 | ~~It's not an issue for NRN, and avoids sending multiple events due to SSR/CSR, but it could be a limitation depending on your business needs.~~
72 | See [https://github.com/amplitude/Amplitude-JavaScript/issues/164](https://github.com/amplitude/Amplitude-JavaScript/issues/164)
73 | - They released [`Amplitude-Node`](https://github.com/amplitude/Amplitude-Node) since then. We haven't tried it and it's not used by NRN.
74 |
75 | ---
76 |
77 | ## Dependencies
78 |
79 | > Amplitude is used to collect usage metrics (analytics) of the application.
80 |
81 | Amplitude **is used only on the frontend part of the application**. It is composed of two parts:
82 | - [`@amplitude/react-amplitude`](https://github.com/amplitude/react-amplitude): React components easy to use, see their [blog post](https://amplitude.engineering/introducing-react-amplitude-d7b5258bc708).
83 | - [`amplitude-js`](https://github.com/amplitude/Amplitude-JavaScript): The JS SDK, only compatible from the browser. (They're working on making it [compatible with SSR](https://github.com/amplitude/Amplitude-JavaScript/issues/164))
84 |
85 | See the [documentation example at react-amplitude](https://github.com/amplitude/react-amplitude#example-instrumenting-tic-tac-toe-from-facebooks-intro-to-react-tutorial) to understand how it's meant to be used.
86 | We only use `react-amplitude` to manipulate events.
87 |
88 | ---
89 |
90 | ## Chrome developer debug tool
91 |
92 | > The amplitude team has released a Chrome plugin to see the events from the browser.
93 | >
94 | > It is a **must-have** when working with Amplitude. It's very simple to use and quite helpful.
95 |
96 | - [Tutorial](https://help.amplitude.com/hc/en-us/articles/360003032451-Instrumentation-Explorer-Debugger)
97 | - [Chrome plugin](https://chrome.google.com/webstore/detail/amplitude-instrumentation/acehfjhnmhbmgkedjmjlobpgdicnhkbp)
98 |
99 | ---
100 |
101 | ## Resources
102 |
103 | - [https://amplitude.com/](https://amplitude.com/)
104 | - [https://developers.amplitude.com/](https://developers.amplitude.com/)
105 | - [https://amplitude.com/blog/category/inside-amplitude](https://amplitude.com/blog/category/inside-amplitude)
106 | - [https://help.amplitude.com/hc/en-us](https://help.amplitude.com/hc/en-us)
107 |
--------------------------------------------------------------------------------
/guides/api-endpoints/index.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: API endpoints
4 | parent: Guides
5 | nav_order: 130
6 | has_children: false
7 | ---
8 |
9 |
10 |
11 | Built-in API endpoints
12 |
13 |
14 |
15 | ---
16 |
17 | # API endpoints
18 | {: .no_toc }
19 |
20 | Next Right Now comes with a few built-in API endpoints described below.
21 |
22 | {% include page-toc.md %}
23 |
24 | ---
25 |
26 | ## **GET** `/api/autoRedirectToLocalisedPage`
27 |
28 | - `payload`: None
29 |
30 | Meant to be used to redirect a non i18n-page towards its i18n page counterpart.
31 |
32 | Used automatically by Next.js `rewrites` rules (`next.config.js`) that match the pattern.
33 |
34 | > Ex: `GET /api/autoRedirectToLocalisedPage` for page `/terms` might redirect to `/en/terms`
35 |
36 | ---
37 |
38 | ## **GET** `/api/error`
39 |
40 | - `payload`: None
41 |
42 | Throws an error upon being called.
43 |
44 | Mock API endpoint whose sole purpose is to throw an error, nothing else.
45 | Meant to be used to check whether monitoring (Sentry) works as expected.
46 |
47 | ---
48 |
49 | ## **GET** `/api/preview`
50 |
51 | - `payload`: `query`
52 | - `stop`: Whether to start/stop the Preview Mode.
53 | - `redirectTo`: Url to redirect to once the preview mode has been started/stopped.
54 |
55 | Preview Mode API.
56 |
57 | Enables and disables preview mode.
58 |
59 | ---
60 |
61 | ## **GET** `/api/startVercelDeployment`
62 |
63 | - `payload`: `query`
64 | - `customerAuthToken`: Customer authentication token.
65 | - `platformReleaseRef`: Release reference of the platform. Basically, a Git commit hash, branch name, or tag.
66 | The ref used will be used to locate what version of the source code should be used for the deployment.
67 | - `redirectTo`: Url to redirect to, once the deployment has been triggered.
68 | - `forceNoRedirect`: Force option to avoid being redirected.
69 | Meant to be used when debugging, to avoid being redirected all the time, but stay on the page instead.
70 |
71 | Starts a new Vercel deployment, for the current customer.
72 |
73 | Meant to be used from an external web platform (e.g: CMS, Back Office, etc.) to trigger a new production deployment that will replace the currently deployed instance, once deployed.
74 |
75 | Endpoint meant to be integrated into 3rd party tools, so it might be used by non-technical people.
76 | (e.g: customer "editor" role, customer success, customer support, etc.)
77 |
78 | ### Related environment variables
79 |
80 | - `GITHUB_DISPATCH_TOKEN`: Github "personal access token".
81 | - Can be generated at "Settings > Developer settings > Personal access tokens" at [https://github.com/settings/tokens](https://github.com/settings/tokens).
82 | - Required if the repository is private.
83 | - Unnecessary if the repository is public.
84 | - Needs the following scopes:
85 | - Repo (FULL)
86 | - Workflow
87 |
88 | > If `GITHUB_DISPATCH_TOKEN` is not set, the app will work anyway, it just won't be able to deploy new instances through the "startVercelDeployment" API.
89 |
90 | ---
91 |
92 | ## **GET** `/api/status`
93 |
94 | - `payload`: None
95 |
96 | Prints the "status" of the deployed instance.
97 |
98 | Prints useful information regarding the deployment.
99 | Meant to be used for debugging purposes.
100 | Can also be used as "ping endpoint" to make sure the app is online.
101 |
102 | ----
103 |
104 | ## **POST** `/api/webhooks/deploymentCompleted`
105 |
106 | - `payload`: `query`
107 | - `MANUAL_TRIGGER_CUSTOMER`: Value that was typed in the GHA web page, as "Customer to deploy".
108 | - `CUSTOMER_REF`: Ref of the customer that was actually deployed.
109 | - `STAGE`: Stage (production/staging) used for the deployment.
110 | - `GIT_COMMIT_SHA`: SHA of the git commit used as deployment ref.
111 | - `GIT_COMMIT_REF`: Ref (branch/tag) that was used as deployment ref.
112 | - `GIT_COMMIT_TAGS`: All tags associated with the git commit.
113 |
114 | Webhook callback url, called automatically when a Vercel deployment has reached "READY" state.
115 |
116 | The call is performed by the GitHub Action "send-webhook-callback-once-deployment-ready" job.
117 |
118 | > This is a mock endpoint that doesn't do anything yet. It is invoked when a Vercel deployment is completed.
119 |
120 | ### Related environment variables
121 |
122 | - `VERCEL_DEPLOYMENT_COMPLETED_WEBHOOK`: Defines the url of the API endpoint to call when a Vercel deployment completes.
123 |
124 | > If `VERCEL_DEPLOYMENT_COMPLETED_WEBHOOK` is not set, the app will work anyway.
125 |
--------------------------------------------------------------------------------
/guides/ci-cd/gha-auto-git-release.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: GitHub Action - Auto release
4 | parent: CI/CD
5 | grand_parent: Guides
6 | nav_order: 10
7 | ---
8 |
9 | # GitHub Action - Auto release
10 | {: .no_toc }
11 |
12 |
13 | Automatically tag and release when changes land on any branch.
14 |
15 | Tag and release changes on the master branch, as releases. (one release per commit)
16 | Tag and pre-release changes on the other branches, as pre-releases with a "x" as "patch" indicator.
17 | (one release per branch, the release is updated at every push)
18 |
13 | Runs unit and coverage tests, then uploads the coverage results to the Code Climate dashboard.
14 |
15 |
16 | {% include page-toc.md %}
17 |
18 | ---
19 |
20 | ## Workflow file(s)
21 |
22 | This action is related to the workflow file:
23 |
24 | - `.github/workflows/auto-git-release.yml`
25 |
26 | ---
27 |
28 | ## Configuring the action
29 |
30 | ### Required GitHub secrets
31 |
32 | > List of necessary requirements for NRN `Update Code Climate test coverage` automation to work properly.
33 |
34 | - `CC_TEST_REPORTER_ID`: Used to associate the Code Climate coverage report to the proper Code Climate project.
35 | 1. Get it from Code Climate in ["Repo settings > Test coverage"](https://codeclimate.com/repos/5e574bdbe2471e01770170f7/settings/test_reporter).
36 | 1. Create the `CC_TEST_REPORTER_ID` as [Github secret](https://github.com/UnlyEd/next-right-now/settings/secrets) for your app.
37 |
--------------------------------------------------------------------------------
/guides/css-in-js/index.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: CSS-in-JS
4 | parent: Guides
5 | nav_order: 80
6 | has_children: true
7 | ---
8 |
9 |
10 |
11 | CSS-in-JS is a styling technique where JavaScript is used to style components. Next Right Now uses Emotion as its CSS-in-JS library.
12 |
13 |
14 |
15 | ---
16 |
17 | # About Emotion
18 |
19 | > Emotion is a library designed for writing css styles with JavaScript. [https://emotion.sh/docs/introduction](https://emotion.sh/docs/introduction)
20 |
21 | Next.js provides CSS-in-js using [`styled-jsx`](https://github.com/vercel/styled-jsx), but we dislike it for several reasons. It's not very intuitive to write
22 | styles that way, and it needs extra dependencies/configuration to work with nested components and such.
23 |
24 | Instead, we use [Emotion](https://emotion.sh/docs/introduction) in this project, which allows writing components using either the `styled` notation, or
25 | the `css` notation.
26 |
27 | It's strongly recommended reading the [official documentation](https://emotion.sh/docs/introduction) about how to use it.
28 |
--------------------------------------------------------------------------------
/guides/css-in-js/remove-emotion.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: How to remove Emotion
4 | parent: CSS-in-JS
5 | grand_parent: Guides
6 | nav_order: 20
7 | ---
8 |
9 | ## How to remove Emotion
10 |
11 | > We strongly recommend to keep Emotion. You can use both Styled Component approach and inline styles, it should fit all css-related needs.
12 |
13 | 1. Remove the following libraries:
14 | - [`@emotion/core`](https://emotion.sh/docs/css-prop): Necessary to use emotion, with built-in `css` notation support.
15 | - [`@emotion/styled`](https://emotion.sh/docs/styled): Necessary to used the `styled` notation.
16 | - [`emotion-theming`](https://www.npmjs.com/package/emotion-theming): Theming library inspired by styled-components
17 | 1. Remove their components usage in the source code + `/** @jsx jsx */`
18 |
--------------------------------------------------------------------------------
/guides/css-in-js/use-emotion.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: How to use Emotion
4 | parent: CSS-in-JS
5 | grand_parent: Guides
6 | nav_order: 10
7 | ---
8 |
9 | # How to use Emotion
10 | {: .no_toc }
11 |
12 |
13 | Advices and "must-know" things regarding Emotion usage.
14 |
15 |
16 | {% include page-toc.md %}
17 |
18 | ---
19 |
20 | ## Usage
21 |
22 | We won't cover usage of Emotion in this documentation, please refer to the [official documentation](https://emotion.sh/docs/introduction) about how to
23 | use it.
24 |
25 | Next Right Now supports the following ways of using Emotion:
26 | - [Using `css` prop](https://emotion.sh/docs/css-prop)
27 | - [Using `styled component`](https://emotion.sh/docs/styled)
28 |
29 | It's up to you to decide how you prefer to use Emotion. Next Right Now doesn't advise or enforce any strong opinion on this matter, it's a personal choice.
30 |
31 | > At Unly, we usually use the `css` prop. In some rare cases, we find the `styled component` approach makes more sense. We eventually use both, but have a preference for the `css` way.
32 |
33 | ### SSR
34 |
35 | SSR is already configured and compatible with Next.js, since Emotion v10. [Source](https://emotion.sh/docs/ssr#nextjs)
36 | You don't have anything to do.
37 |
38 | ## Dependencies
39 |
40 | - [`@emotion/core`](https://emotion.sh/docs/css-prop): Necessary to use emotion, with built-in `css` notation support.
41 | - [`@emotion/styled`](https://emotion.sh/docs/styled): Necessary to use the `styled` notation.
42 | - [`emotion-theming`](https://www.npmjs.com/package/emotion-theming): Theming library inspired by styled-components
43 |
44 | ## Resource
45 |
46 | - [Introduction to Emotion](https://emotion.sh/docs/introduction)
47 |
--------------------------------------------------------------------------------
/guides/demo-examples/index.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: Demo examples
4 | parent: Guides
5 | nav_order: 100
6 | has_children: true
7 | ---
8 |
9 | NRN comes with one built-in demo per preset, each demo showcases the important features and utilities that are built-in within the selected preset.
10 |
11 | Therefore, each demo is slightly different for each preset.
12 |
13 | > While a demo is great at showcasing features and explaining concepts, but you'll most likely want to tear it down to build your own app instead.
14 | >
15 | > We explain how to do that below.
16 |
17 | Here are a few of the existing demo:
18 | - [`v2-mst-aptd-at-lcz-sty`](../../available-presets/v2-mst-aptd-at-lcz-sty#demo)
19 | - [`v2-mst-aptd-gcms-lcz-sty`](../../available-presets/v2-mst-aptd-gcms-lcz-sty#demo)
20 |
--------------------------------------------------------------------------------
/guides/demo-examples/remove-demo-examples.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: How to remove the built-in demo examples
4 | parent: Demo examples
5 | grand_parent: Guides
6 | nav_order: 10
7 | ---
8 |
9 | # How to remove the built-in demo examples
10 | {: .no_toc }
11 |
12 |
13 | Guide about how to remove the default demo examples so you can build your own app instead.
14 |
15 | The demo is great at showcasing features and explaining concepts, but you'll most likely want to tear it down, eventually.
16 |
17 |
18 | ---
19 |
20 | ## Example - Guide on how to remove the demo examples from the preset [v2-mst-aptd-at-lcz-sty](../../available-presets/v2-mst-aptd-at-lcz-sty)
21 |
22 | It's very easy to do, and **can be done in a few seconds**.
23 | We'll take the example of the `v2-mst-aptd-at-lcz-sty` preset, that lives in [this github repo branch](https://github.com/UnlyEd/next-right-now/tree/v2-mst-aptd-at-lcz-sty).
24 |
25 | > It's really up to you to decide what you do with the built-in demo. It can be used as reference for other teammates or for yourself later.
26 | > You could, for instance, keep it around under the same /examples/ path, and disallow that route on production.
27 |
28 | ### Change the Homepage entry point to load a different file
29 |
30 | 1. Go to the entrypoint for the whole app (AKA "homepage"), located under [`src/pages/[locale]/index.tsx`](https://github.com/UnlyEd/next-right-now/blob/v2-mst-aptd-at-lcz-sty/src/pages/%5Blocale%5D/index.tsx)
31 | 1. As you can notice, that's where we import the demo examples using `import DocsHomePage, { getStaticPaths as getStaticPathsHomePage, getStaticProps as getStaticPropsHomePage } from './examples/';`
32 | 1. You can either delete this file entirely and copy the `pageTemplateSSG` or `pageTemplateSSR` file (and rename it `index.tsx` so that it acts as the new homepage), or just replace the existing file content with your own app
33 |
34 | By doing this, you'll basically bypass the whole `/examples` files, which are still accessible at [http://localhost:8888/examples](http://localhost:8888/examples) if you wish to use them as local reference.
35 | Feel free to delete the whole `/examples` folder when you don't need it anymore. (we advise to keep it around until you're familiar with the preset, as it's a great source of inspiration)
36 |
37 | ### Deleting all demo and example files
38 |
39 | If you want to get rid of all the demo files, you can remove the following:
40 | - `src/components/doc`
41 | - `src/pages/[locale]/examples`
42 |
43 | Also, note the files `SSG.ts` and `SSR.ts` define the `getExamplesCommonStaticPaths` and `getExamplesCommonStaticProps` used by all the examples.
44 |
45 | You should keep those around if you want to keep the demo around.
46 | Alternatively, you can move the `getExamplesCommonStaticPaths` and `getExamplesCommonStaticProps` implementations to `getCommonStaticPaths` and `getCommonStaticProps`.
47 |
48 | > As long as you don't change the implementation of `getExamplesCommonStaticPaths` or `getExamplesCommonStaticProps`, you don't need to change anything there.
49 | >
50 | > You'll probably need to change the implementation of `getCommonStaticPaths` and `getCommonStaticProps` if you implement your own business logic.
51 | > When you do so, you can either duplicate the existing code about the examples, if you want to keep those around, or simply remove both `getExamplesCommonStaticPaths` and `getExamplesCommonStaticProps`.
52 |
53 |
--------------------------------------------------------------------------------
/guides/graphql-api/index.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: GraphQL API
4 | parent: Guides
5 | nav_order: 20
6 | has_children: true
7 | ---
8 |
9 |
10 |
11 | GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools.
12 |
13 |
14 |
15 | ---
16 |
17 | # About GraphQL
18 |
19 | [Learn more](https://graphql.org/)
20 |
21 | ## GraphQL vs other API protocols
22 |
23 | > If you want to learn about the pros/cons of GraphQL vs other API protocols, we suggest reading [Comparing API Architectural Styles: SOAP vs REST vs GraphQL vs RPC](https://levelup.gitconnected.com/comparing-api-architectural-styles-soap-vs-rest-vs-graphql-vs-rpc-84a3720adefa)
24 |
25 | ## GraphQL and Next Right Now
26 |
27 | Next Right Now provides various presets. Some of those presets include a built-in GraphQL support.
28 |
29 | In particular, the preset `v2-mst-aptd-gcms-lcz-sty` includes GraphQL support, using GraphCMS vendor. _(`gcms`)_
30 |
--------------------------------------------------------------------------------
/guides/graphql-api/setup-graphcms.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: How to setup GraphCMS
4 | parent: GraphQL API
5 | grand_parent: Guides
6 | nav_order: 10
7 | ---
8 |
9 | # How to setup GraphCMS
10 | {: .no_toc }
11 |
12 |
13 | Step-by-step guide about how to create and properly configure your GraphCMS account.
14 |
15 |
16 | {% include page-toc.md %}
17 |
18 | ---
19 |
20 | ## Tips
21 |
22 | - Using the coupon code **`unly-nrn`** will grant you a **3-month 15% discount** on any premium plans.
23 | - Free support is available on their [Slack channel](https://graphcms.slack.com) _(and they're awesome)_
24 |
25 | ## Video tutorial (10 minutes)
26 |
27 | [](http://youtu.be/ig5a7LXTiBM?hd=1)
28 |
29 | > This video explains how to create a GraphCMS account and configure locales, versions, auth tokens and gives an overview of the settings.
30 | >
31 | > _This video is outdated, as it was recorded in February 2020, when NRN Demo was using the GraphCMS v1. Since then, the Demo has been upgraded to v2, and the UI has changed a bit._
32 |
33 | ---
34 |
35 | ## Create GraphCMS account
36 |
37 | - [Create a free account on GraphCMS](https://graphcms.com/?ref=unly-nrn)
38 | - Create a new project
39 | - **Make sure to select the right region**, as it cannot be changed afterwards.
40 | _The "right region" is the one that's the closest to your customers._
41 |
42 | ---
43 |
44 | ## Learn how to configure your GraphCMS project
45 |
46 | #### Public API Permissions
47 |
48 | By default, your `Public API Permissions` is set to **`PROTECTED`**.
49 |
50 | But, it is also possible to allow anyone, without any authentication, to interact with your API.
51 | This is managed using `Public API Permissions`:
52 | - `QUERY`: Allow anyone to query the data. But won't allow to mutate any data. (read-only)
53 | - `MUTATION`: Allows anyone to mutate the data. But won't allow to query any data. (write-only)
54 | - `OPEN`: Allows any consumer to both query and mutate the data.
55 | - **`PROTECTED`** (default): This means an authentication is required to perform any operation on the API, and the permission scope is managed using `Permanent Auth Token`.
56 | **This is what we will be using in this guide.**
57 |
58 | > We considered the most common use case is to allow to fetch data from your API, protected by an auth token.
59 |
60 | The decision eventually depends on your own requirements. But please bear with us for now and keep the default `PROTECTED` configuration.
61 |
62 | #### Permanent Auth Token
63 |
64 | You may allow each token a different permissions scope:
65 | - `QUERY`: Allows any consumer to query the data. But won't allow to mutate any data. (read-only)
66 | **This is what we will be using in this guide, because we only need to fetch the data and not mutate them.**
67 | - `MUTATION`: Allows any consumer to mutate the data. But won't allow to query any data. (write-only)
68 | - `OPEN`: Allows any consumer to both query and mutate the data.
69 |
70 | ---
71 |
72 | ## Configure your GraphCMS project
73 |
74 | - Copy the `Master endpoint` and create a `GRAPHQL_API_ENDPOINT` env variable in your `.env.local`
75 | - **Hint**: It starts with `https://api-euwest.graphcms.com/v1...`
76 | - Create a `Permanent Auth Token` with `QUERY` permissions.
77 | - This will generate a token that can be used to authenticate to your GraphCMS API endpoint and fetch data.
78 | - Copy this token, you won't be able to see it again.
79 | - Use the previously copied auth token and create a `GRAPHQL_API_KEY` env variable in your `.env.local`
80 | - If you have already configured Vercel, and if you want to deploy your app online, you must also configure Vercel secrets
81 | - Replace the `GRAPHQL_API_ENDPOINT` in all `vercel.*.json` files (this is not a secret because it's not considered sensitive)
82 | - `vercel secrets add nrn-graphql-api-key YOUR_API_KEY`
83 | - Your app is now properly configured and will be able to run GraphQL queries to fetch data from your app.
84 |
85 | **Important note:**
86 | Do not expect your app to actually work at this time, you've just created a new GraphCMS project which doesn't match the expected GraphQL API structure, all requests will fail and that's expected.
87 |
88 | ### (Optional) Replicating the GraphCMS data structure
89 |
90 | If you want to replicate the online demo on your local computer, you will have to use the same GraphCMS schema structure so that queries can be executed successfully.
91 |
92 | We use a particular GraphCMS [data structure for our demo](../../reference/demo-database-structure), you'll need to replicate it on your GraphCMS project.
93 | - It is recommended to watch the video if you haven't done it already.
94 | - It's basically WYSIWYG, creating new fields on GraphCMS models, all changes are applied immediately (CMS + API are dynamically updated when the GraphCMS schema is changed)
95 |
96 | **Some considerations:**
97 | - Any missing field will throw a GraphQL error. (querying a field that doesn't exist on the GraphCMS API)
98 | - The field types must match. (Some mismatch would still succeed, like using a `Multi line text` or `Markdown` instead of `Single line text` because it doesn't affect the structure of the GraphQL query, but better use exactly the same types)
99 | - You can have more fields on your GraphCMS schema. (Having more fields is not an issue, the GraphQL queries will work nonetheless)
100 |
101 | Once you've created all fields on GraphCMS, you can run your app locally using `yarn start` and it should work properly.
102 |
103 | ---
104 |
105 |
106 |
107 | [How to use GraphCMS >](./use-graphcms){: .btn .btn-purple }
108 |
109 |
110 |
--------------------------------------------------------------------------------
/guides/graphql-api/use-graphql.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: How to use GraphQL
4 | parent: GraphQL API
5 | grand_parent: Guides
6 | nav_order: 20
7 | ---
8 |
9 | # How to use GraphQL
10 | {: .no_toc }
11 |
12 | Advices and "must-know" things regarding GraphQL usage.
13 |
14 | {% include page-toc.md %}
15 |
16 | ---
17 |
18 | ## Configure in-editor GraphQL support, for WebStorm IDE
19 |
20 | Install [JS GraphQL IntelliJ Plugin](https://github.com/jimkyndemeyer/js-graphql-intellij-plugin): GraphQL language support for WebStorm, IntelliJ IDEA and
21 | other IDEs based on the IntelliJ Platform.
22 |
23 | The plugin is available using WebStorm directly. To install it, open your IDE "Settings", "Plugins", "Marketplace" and search for "GraphQL".
24 |
25 | The plugin is built-in and should be available as soon as you open the project using WebStorm.
26 |
27 | The usage of both `gql` and the IntelliJ GraphQL plugin is awesome, it allows writing GraphQL queries (see `src/gql`) and have auto-completion and validation
28 | from WebStorm itself.
29 |
30 | To refresh the GraphQL spec, just run the `.graphqlconfig` file by opening it and run the stage you want to sync (usually staging).
31 |
32 | ## Dependencies
33 |
34 | ### GraphQL deps
35 |
36 | - [`graphql`](https://www.npmjs.com/package/graphql): Client for connecting to a GraphQL endpoint.
37 | - [`graphql-tag`](https://www.npmjs.com/package/graphql-tag): Helpful utilities for parsing GraphQL queries.
38 | Useful to write plain-text GraphQL query using the `gql` tag, that can be validated by other tools, such as **JS GraphQL IntelliJ Plugin**.
39 |
40 | ### `react-apollo` deps
41 |
42 | We use [Apollo](https://github.com/apollographql/react-apollo) to manipulate our GraphQL endpoint.
43 |
44 | React Apollo allows you to fetch data from your GraphQL server and use it in building complex and reactive UIs using the React framework. React Apollo may be used in any context that React may be used.
45 |
46 | - [`apollo-boost`](https://www.npmjs.com/package/apollo-boost): Apollo Boost is a zero-config way to start using Apollo Client. It includes some sensible defaults, such as our recommended InMemoryCache and HttpLink, which come configured for you with our recommended settings.
47 | **Even though it may seems unused, this package is required as peer-dependency**.
48 | - [`apollo-cache-inmemory`](https://www.npmjs.com/package/apollo-cache-inmemory): Recommended cache implementation for Apollo Client 2.0. InMemoryCache is a normalized data store that supports all of Apollo Client 1.0's features without the dependency on Redux.
49 | - [`apollo-client`](https://www.npmjs.com/package/apollo-client): Apollo Client is a fully-featured caching GraphQL client with integrations for React, Angular, and more. It allows you to easily build UI components that fetch data via GraphQL.
50 | - [`apollo-link-http`](https://www.npmjs.com/package/apollo-link-http): The http link is a terminating link that fetches GraphQL results from a GraphQL endpoint over an http connection.
51 | - [`react-apollo`](https://www.npmjs.com/package/react-apollo): React Apollo allows you to fetch data from your GraphQL server and use it in building complex and reactive UIs using the React framework. React Apollo may be used in any context that React may be used. In the browser, in React Native, or in Node.js when you want to do server-side rendering.
52 |
53 | Our implementation is based on [this example](https://github.com/tomanagle/GraphQL-Apollo-Next.js) and uses the [`react hooks`](https://reactjs.org/docs/hooks-intro.html) recent feature.
54 |
55 | > It works fine with both SSR and client-side navigation.
56 | >
57 | > A universal [HOC](https://reactjs.org/docs/higher-order-components.html) is used to fetch data from our GraphQL endpoint: [withUniversalGraphQLDataLoader](src/hoc/withUniversalGraphQLDataLoader.ts). (both from browser and SSR)
58 | >
59 | > We provide some headers on-the-fly (for I18n), that are added per-query basis.
60 |
--------------------------------------------------------------------------------
/guides/i18n/add-locale.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: How to add a new locale
4 | parent: I18n
5 | grand_parent: Guides
6 | nav_order: 40
7 | ---
8 |
9 |
10 |
11 | This guide explains how to add a new Locale to a project created using Next Right Now.
12 |
13 |
14 |
15 | ---
16 |
17 | # How to add a new locale
18 |
19 | > For instance, let's say we want to add a new `fr-CA` locale.
20 |
21 | ## Adding a new `supportedLocales`
22 |
23 | In the `src/i18ncConfig.js`, add the `fr-CA` locale in the `supportedLocales` array, as follows:
24 |
25 | ```js
26 | const supportedLocales = [
27 | { name: 'fr', lang: 'fr' },
28 | { name: 'fr-CA', lang: 'fr' }, // XXX New addition
29 | { name: 'en-US', lang: 'en' },
30 | { name: 'en', lang: 'en' },
31 | ];
32 | ```
33 |
34 | This will immediately allow routes like `/fr-CA/` to be used within the app.
35 |
36 | ## Adapting your localization provider
37 |
38 | You might also need to make some changes in your localization provider (e.g: Locize).
39 |
40 | ### Locize
41 |
42 | If you use Locize, you'll need to create a new "Namespace" `fr-CA` in your project.
43 |
44 | _There is an ongoing issue with the Locize implementation, see [#200](https://github.com/UnlyEd/next-right-now/issues/200)._
45 |
--------------------------------------------------------------------------------
/guides/i18n/index.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: I18n
4 | parent: Guides
5 | nav_order: 30
6 | has_children: true
7 | ---
8 |
9 |
14 |
15 | ---
16 |
17 | # About I18n
18 |
19 | Internationalization is split in several parts:
20 | - Routing: How to resolve the proper page.
21 | - Content translation: How to programmatically translate a translation key into its translated value.
22 | - Content management: How to allow human to configure and translate content.
23 |
24 | The Next.js framework only offers a solution for the "Routing" part, and does so since the `v10` release.
25 |
26 | Next Right Now offers a solution for the "Routing", "Content Translation" and "Content management" parts, as described below.
27 |
28 | # Official I18n routing implementation
29 |
30 | **NRN uses its own i18n routing implementation instead of the official implementation.**
31 |
32 | This is because the Next.js framework released an i18n routing implementation [since `v10`](https://nextjs.org/docs/advanced-features/i18n-routing) in the summer of 2020, while NRN released its own implementation in early 2020.
33 |
34 | Even though the official implementation and NRN implementation **are compatible and look much alike**, NRN hasn't updated its own implementation because the official implementation doesn't generate a prefix url for the default locale, and **this is a breaking change**.
35 |
36 | [This issue is being tracked in #194](https://github.com/UnlyEd/next-right-now/issues/194).
37 |
38 | ---
39 |
40 | # Next Right Now I18n routing implementation
41 |
42 | ## Localized pages
43 |
44 | All localized pages must be located in the `src/pages/[locale]` folder.
45 |
46 | The `[locale]` directory is a native Next.js [Dynamic Route](https://nextjs.org/docs/routing/dynamic-routes).
47 |
48 | ## Automatically detect the user locale
49 |
50 | The i18n routing implementation relies on the native Next.js [`rewrites` rules](https://nextjs.org/docs/api-reference/next.config.js/rewrites) which automatically forwards all requests who don't have a `locale` parameter to a special API endpoint.
51 |
52 | [Take a look at the implementation](https://github.com/UnlyEd/next-right-now/blob/f24da10646f1a8225fed537337193fd0707f7ac1/next.config.js#L140-L163).
53 |
54 | All requests that don't contain a `locale` in the url are automatically forwarded (through `rewrites`) to a dedicated API endpoint `/api/autoRedirectToLocalisedPage`.
55 |
56 | There, the API resolves the user languages based on request `accept-language` HTTP header. The `accept-language` is filtered to ignore locales that aren't allowed by the application (see `supportedLocales` in `src/i18nCOnfig.js`).
57 |
58 | Then, it redirects to the initially targeted page, by injecting the resolved locale in the url.
59 |
60 | > When a request already contains the `locale` in the url, the API endpoint `/api/autoRedirectToLocalisedPage` doesn't intercept the request (the `rewrites` rules aren't applied).
61 | >
62 | > In such cases, the requested page is accessed directly, using the traditional Next.js routing.
63 |
64 | ## Costs and limits associated to dynamic routing when hosting on Vercel
65 |
66 | Because we use an API endpoint to resolve the request locale to use when the locale isn't specified in the url, it might incur costs or count toward Vercel limits, due to calling an API endpoint, depending on your plan.
67 |
68 | > As of 2021, most plans are billed per-user and not billed per-usage. **Therefore, most plans shouldn't be affected by how many Serverless Function invocations are made.**
69 | >
70 | > Nevertheless, it's good to keep in mind calls to `/` which are automatically forwarded to the `/api/autoRedirectToLocalisedPage` API endpoint count toward **Serverless Function invocation**,
71 | > and to learn about how the [Vercel limits](https://vercel.com/docs/platform/limits#general-limits) might affect you.
72 |
73 | ## Disabling automatic locale detection
74 |
75 | You might want to use a different implementation and automatically redirect to the `en` version of a page when the locale isn't specified in the url.
76 |
77 | For instance, this might be useful if you don't want to use an API to resolve the user locale.
78 | Also, it would be necessary if you want to export your Next.js app, as it can't have API endpoints then (static build).
79 |
80 | In such cases, the proper way to go would be to change the `rewrites` implementation, so that paths without a `locale` are redirected to the `en` version of the page directly.
81 |
82 | ---
83 |
84 | # Next Right Now "Content localization", using open-source libraries
85 |
86 | The Next.js framework doesn't yet provide any way to translate the content, although it is mentioned in the [official RFC](https://github.com/vercel/next.js/discussions/17078) as an upcoming feature.
87 |
88 | Next Right Now provides a built-in way of translating content, by using the [`i18next`](https://www.i18next.com/) and [`react-i18next`](https://react.i18next.com/) open-source libraries.
89 |
90 | Please refer to their respective documentation to learn more about how they should be used.
91 | You can also find various usage example in our [demos](https://nrn-default.now.sh/en/examples/built-in-features/static-i18n).
92 |
93 | ---
94 |
95 | # Next Right Now "Content management", using a professional "Localization as a service" (Locize)
96 |
97 | [Locize](https://locize.com/?ref=unly-nrn) is a SaaS platform meant to help you manage translations.
98 |
99 | **It's been built by the authors of i18next and react-i18next as a way for them to monetize their open-source contributions.**
100 |
101 | If you use i18next and react-i18next, then using Locize is the logical next move for any non-trivial app.
102 |
103 | > A Unly, we use [Locize](https://locize.com/?ref=unly-nrn) since 2019, and are very much happy with it.
104 |
105 | Locize has been kind enough to provide a free project for hosting the Next Right Now demos translations.
106 |
--------------------------------------------------------------------------------
/guides/i18n/remove-i18n.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: How to remove i18n
4 | parent: I18n
5 | grand_parent: Guides
6 | nav_order: 7
7 | ---
8 |
9 | # How to remove i18n
10 |
11 | ---
12 |
13 | 1. Remove the following libraries:
14 | - [`i18next`](https://www.npmjs.com/package/i18next): i18next is a very popular internationalization framework for browser or any other javascript environment (eg. node.js).
15 | - [`react-i18next`](https://www.npmjs.com/package/react-i18next): Internationalization for react done right. Using the i18next i18n ecosystem.
16 | 1. Remove their components usage in the source code
17 |
--------------------------------------------------------------------------------
/guides/i18n/remove-locize.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: How to remove Locize
4 | parent: I18n
5 | grand_parent: Guides
6 | nav_order: 30
7 | ---
8 |
9 | # How to remove Locize & i18n
10 |
11 | ---
12 |
13 | You may replace Locize by another internationalisation too of your choice. Make sure it is JS universal-friendly though.
14 |
15 | 1. Remove the following libraries:
16 | - [`i18next-locize-backend`](https://www.npmjs.com/package/i18next-locize-backend): This is an i18next backend to be used for locize service. It will load resources from locize server using xhr.
17 | - [`i18next-node-locize-backend`](https://www.npmjs.com/package/i18next-node-locize-backend): This is a i18next backend to be used with node.js for the locize service. It's for the node.js server what the i18next-locize-backend is for the browser.
18 | - [`locize-editor`](https://www.npmjs.com/package/locize-editor): The locize-editor enables you to directly connect content from your website / application with your content on your localization project on locize.
19 | - [`locize-node-lastused`](https://www.npmjs.com/package/locize-node-lastused): This is an i18next plugin or standalone scriot to be used for locize service. It will update last used timestamps on reference keys from your locize project using xhr. It sets the last used date on your reference language's namespaces.
20 | 1. Remove their components usage in the source code
21 | 1. Remove the `NEXT_PUBLIC_LOCIZE_PROJECT_ID`, in `.env`
22 | 1. Remove the `LOCIZE_API_KEY` env var, in `.env.local`
23 |
--------------------------------------------------------------------------------
/guides/i18n/setup-locize.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: How to setup Locize
4 | parent: I18n
5 | grand_parent: Guides
6 | nav_order: 10
7 | ---
8 |
9 | # How to setup Locize
10 | {: .no_toc }
11 |
12 |
13 | Guide about how to properly configure Locize.
14 |
15 |
16 | {% include page-toc.md %}
17 |
18 | ---
19 |
20 | ## Creating Locize account
21 |
22 | The app will throw an error if the `NEXT_PUBLIC_LOCIZE_PROJECT_ID` is not valid.
23 |
24 | - **Tip**: You can skip creating your own Locize account if you use the default `NEXT_PUBLIC_LOCIZE_PROJECT_ID` in `.env`,
25 | but note that **new keys won't be created automatically** because `LOCIZE_API_KEY` in `.env` doesn't hold a valid value and should be defined in `.env.local` with a proper value, instead.
26 |
27 | - [Create a free (2 weeks trial) account on Locize](https://www.locize.app/register?ref=unly-nrn)
28 | - Make sure to keep `i18n format: i18next/locizify` (by default)
29 | - Make sure to select `publish format: json nested`
30 | - Add French and English languages (french is required for the demo to work properly)
31 | - Add a `common` namespace (and remove the default `latest` namespace)
32 | - (Optional) Update the `src/utils/i18nextLocize.ts:referenceLng` (set to `fr` for the demo), you can leave it to `fr` if you created a French version in Locize
33 | - (Optional) Add a `production` version, you won't need it if you don't deploy to production
34 | - Set the `Cache-Control max-age` header value _(ex: `86400`)_ for the `production` version (performances + cost optimizations)
35 | - Copy the `Project Id` and `API Key` from the Locize settings page to the `.env` and `.env.local` (`NEXT_PUBLIC_LOCIZE_PROJECT_ID` and `LOCIZE_API_KEY`, respectively)
36 | - The `NEXT_PUBLIC_LOCIZE_PROJECT_ID` is required for the app to fetch the translations
37 | - The `LOCIZE_API_KEY` is required for the app to automatically create missing keys to Locize, when working locally (See `src/utils/i18nextLocize.ts:saveMissing` option)
38 | **This key is sensitive and must not be shared publicly, as it would allow anyone to update your translations through the API.** (it's not injected in the DOM when not working locally, so you're safe for now)
39 | It is strongly recommended storing it into `.env.local` instead of `.env`, to avoid tracking it by Git.
40 | - If you have already configured Vercel, and if you want to deploy your app online, you must also configure Vercel secrets
41 | - `vercel secrets add nrn-locize-project-id YOUR_PROJECT_ID`
42 | - `vercel secrets add nrn-locize-api-key YOUR_API_KEY`
43 |
44 | That's it! Your Locize project is setup and ready to use!
45 |
46 | ### Locize configuration video tutorial (12 minutes)
47 |
48 | [](http://youtu.be/p7NVIlIGD30?hd=1)
49 |
50 | > This video explains how to create a Locize account and configure versions, languages, namespaces, Caching and how to release new versions to production
51 |
52 | ### Additional i18n/Locize documentation
53 |
54 | - `react-i18next`:
55 | - [Official react-i18next documentation](https://react.i18next.com/)
56 | - [Github react-i18next](https://github.com/i18next/react-i18next)
57 | - [`useTranslation` hook official guide](https://react.i18next.com/latest/usetranslation-hook)
58 | - [`Trans` component official guide](https://react.i18next.com/latest/trans-component)
59 | - [Official i18next documentation](https://www.i18next.com/)
60 |
--------------------------------------------------------------------------------
/guides/i18n/use-i18n.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: How to use i18n
4 | parent: I18n
5 | grand_parent: Guides
6 | nav_order: 1
7 | ---
8 |
9 | # How to use i18n
10 | {: .no_toc }
11 |
12 |
13 | Advices and "must-know" things regarding i18n usage.
14 |
15 |
16 | {% include page-toc.md %}
17 |
18 | ---
19 |
20 | ## Built-in i18next and react-i18next
21 |
22 | Next Right Now provides a built-in way of translating content, by using the [`i18next`](https://www.i18next.com/)
23 | and [`react-i18next`](https://react.i18next.com/) open-source libraries.
24 |
25 | Please refer to their respective documentation to learn more about how they should be used. You can also find various usage example in
26 | our [demos](https://nrn-default.now.sh/en/examples/built-in-features/static-i18n).
27 |
--------------------------------------------------------------------------------
/guides/ide/index.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: IDE
4 | parent: Guides
5 | nav_order: 1
6 | has_children: true
7 | ---
8 |
9 | # About WebStorm
10 |
11 | We use [WebStorm IDE](https://www.jetbrains.com/webstorm/) because it's one of the best out there, and we're very used to it.
12 |
13 | Therefore, we will provide **advanced WebStorm advices and configuration**.
14 |
15 | > This is a personal preference and **you can use any IDE** of your choosing with NRN.
16 | >
17 | > If you don't know what IDE to use, then we advise using [Visual Studio Code](https://code.visualstudio.com/), which is completely free, and wonderful too.
18 |
19 |
20 | As of 2022, we recommend either:
21 |
22 | - [WebStorm](https://www.jetbrains.com/webstorm/) (paid, free for students)
23 | - or [VSCode](https://code.visualstudio.com/) (free, OSS)
24 |
25 | > Please contribute and share tips about your IDE, if you wish to see NRN provide advanced advices and configuration for other tools, such as VSCode.
26 |
--------------------------------------------------------------------------------
/guides/ide/setup-webstorm.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: How to setup WebStorm
4 | parent: IDE
5 | grand_parent: Guides
6 | nav_order: 10
7 | ---
8 |
9 | # How to setup WebStorm IDE
10 | {: .no_toc }
11 |
12 |
13 | Guide about how to properly configure your WebStorm IDE.
14 |
15 |
16 | {% include page-toc.md %}
17 |
18 | ---
19 |
20 | ## Exclude write-heavy directories to improve performances
21 |
22 | Configure your IDE not to index `.next` and `.vercel` folders as they will eat a lot of your RAM because their files are changed very frequently!
23 |
24 | On WebStorm, right click on the folders and select `Mark directory as > Excluded`.
25 |
--------------------------------------------------------------------------------
/guides/ide/use-vscode.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: How to use VS Code
4 | parent: IDE
5 | grand_parent: Guides
6 | nav_order: 20
7 | ---
8 |
9 | # How to use VS Code IDE
10 | {: .no_toc }
11 |
12 | {% include page-toc.md %}
13 |
14 | ---
15 |
16 | ## Interactive debug mode
17 |
18 | > I don't use VS Code myself, so I haven't tried this for real.
19 |
20 | See [this discussion](https://github.com/vercel/vercel/issues/2864#issuecomment-963533339) to use VS Code debugging.
21 |
22 | ---
23 |
--------------------------------------------------------------------------------
/guides/ide/use-webstorm.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: How to use WebStorm
4 | parent: IDE
5 | grand_parent: Guides
6 | nav_order: 20
7 | ---
8 |
9 | # How to use WebStorm IDE
10 | {: .no_toc }
11 |
12 | {% include page-toc.md %}
13 |
14 | ---
15 |
16 | ## Interactive debug mode
17 |
18 | In order to use step-by-step debugging (AKA "interactive debug"), there is a special configuration to apply to WebStorm IDE.
19 |
20 | You can start the project in **debug mode** [by running the WebStorm "Debug" configuration in debug mode](https://youtu.be/3vbkiRAT4e8)
21 |
22 | Beware that this will only allow for back-end debugging.
23 | Frontend debug should be performed from the browser itself.
24 |
25 | ### Dependencies
26 |
27 | [Read more](../../reference/dependencies#debug-webstorm)
28 |
29 | ---
30 |
--------------------------------------------------------------------------------
/guides/index.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: Guides
4 | nav_order: 40
5 | has_children: true
6 | ---
7 |
8 | # Guides
9 |
10 | For each topic, learn how to:
11 | - **Configure** (step-by-step tutorial about initial setup and must-know configuration settings)
12 | - **Use** (links to official docs and overview explanation)
13 | - **Remove** (explanation about what packages to remove and where/how source code is impacted)
14 |
--------------------------------------------------------------------------------
/guides/monitoring/index.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: Monitoring
4 | parent: Guides
5 | nav_order: 50
6 | has_children: true
7 | ---
8 |
9 |
14 |
15 | ---
16 |
17 | # About Sentry
18 |
19 | Sentry provides an event monitoring solution that helps all software teams discover, triage, and prioritize errors in real-time.
20 |
21 | We use Sentry to catch errors (and various events) that happen within the application.
22 | They are available at [https://sentry.io/](https://sentry.io/) for any developers in the team.
23 |
24 | Those errors can be sent automatically to a Slack channel, by email, etc.
25 |
26 | ## Resources
27 |
28 | - [https://sentry.io/welcome/](https://sentry.io/welcome/)
29 | - [https://docs.sentry.io/](https://docs.sentry.io/)
30 | - [Official "Getting started" guide](https://docs.sentry.io/error-reporting/quickstart/?platform=javascript)
31 | - [Capturing errors](https://docs.sentry.io/error-reporting/capturing/?platform=javascript)
32 | - [Configuration](https://docs.sentry.io/error-reporting/configuration/?platform=javascript)
33 | - [Using "context" for events](https://docs.sentry.io/enriching-error-data/context/?platform=javascript)
34 | - [Using "breadcrumbs" for events](https://docs.sentry.io/enriching-error-data/breadcrumbs/?platform=javascript)
35 | - [How to blacklist sensitive data tracking (GDPR, security)](https://docs.sentry.io/data-management/sensitive-data/)
36 |
--------------------------------------------------------------------------------
/guides/monitoring/remove-sentry.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: How to remove Sentry
4 | parent: Monitoring
5 | grand_parent: Guides
6 | nav_order: 30
7 | ---
8 |
9 | # How to remove Sentry
10 |
11 | ---
12 |
13 | You may replace Sentry by another monitoring tool of your choice. Make sure it is JS universal-friendly though.
14 |
15 | 1. Remove the following libraries:
16 | - [`@sentry/browser`](https://www.npmjs.com/package/@sentry/browser): Package to use from the browser.
17 | - [`@sentry/node`](https://www.npmjs.com/package/@sentry/node): Package to use from the server.
18 | 1. Remove their components usage in the source code
19 | 1. Remove the `SENTRY_DSN` env var, in `.env.local`
20 | 1. Remove alias in [next.config.js](next.config.js) `config.resolve.alias['@sentry/node'] = '@sentry/browser';`
21 |
--------------------------------------------------------------------------------
/guides/monitoring/setup-sentry.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: How to setup Sentry
4 | parent: Monitoring
5 | grand_parent: Guides
6 | nav_order: 10
7 | ---
8 |
9 | # How to setup Sentry
10 | {: .no_toc }
11 |
12 |
13 | Guide about how to properly configure Sentry.
14 |
15 |
16 | {% include page-toc.md %}
17 |
18 | ---
19 |
20 | ## Creating Sentry account
21 |
22 | - **Tip**: If you don't want to create an account, you can use `https://14fa1cae05079675b18cd05403ae5c48@sentry.io/1234567` as `SENTRY_DSN` in `.env.local`, it will not catch any error, but it will allow for online deployment (it's a dummy value)
23 |
24 | - [Create a free account on Sentry](https://sentry.io/signup/?ref=unly-nrn)
25 | - Create a new project
26 | - Select "React" as project type
27 | - **Tip**: You **should** create only one project, even if you use a multi-tenants setup, because all customers will be using the same error monitoring project
28 | - You can find your Sentry DSN at [https://sentry.io/settings/TEAM_NAME/projects/PROJECT_NAME/keys/](https://sentry.io/settings/TEAM_NAME/projects/PROJECT_NAME/keys/)
29 | - If you have already configured Vercel, and if you want to deploy your app online, you must also configure Vercel secrets
30 | - `vercel secrets add nrn-sentry-dsn YOUR_SENTRY_DSN`
31 |
32 | That's it! Your Sentry account is ready to use!
33 |
34 | ## Configuring Sentry alerts
35 |
36 | At Unly, we use Sentry to forward issues to our Slack channel automatically.
37 |
38 | While this is completely optional, and merely a recommandation/guide from us, we advise you to do something similar so you get notified when things go wrong.
39 |
40 | ### Slack configuration and notifications
41 |
42 | We use 3 different Slack channels:
43 | - Production
44 | - Staging
45 | - Development
46 |
47 | Each channel is configured by our Slack members differently. Our Customer Success team has access to the Production channel only, to avoid disturbing them needlessly.
48 | Developers have access to all channels, but the Development channel is muted for everyone. It's still useful to manually check if something happens there, when debugging something locally.
49 |
50 | ### Sentry alerts configuration
51 |
52 | We split our alerts in two parts:
53 | - The unknown events and issues
54 | - The known events (those with an `alertType` tag set)
55 |
56 | This helps to configure the Slack behavior slightly differently. Also, we route some specific alerts to specific Slack channels based on their `alertType` value, for specific teams and purposes.
57 |
58 | The below configuration is how we recommend configuring your Sentry alerts.
59 | The 2 first alerts are the most important, others are merely examples of what you could do.
60 | They make most sense if you need to deal with different alerting behavior based on the `alertType` value.
61 |
62 | #### Alert - Production all events
63 |
64 | - Environment: `production`
65 | - Name: Production all events
66 | - When "additional triggers": `any`
67 | - A new issue is created
68 | - The event occurs
69 | - If: None
70 | - Then: Send a Slack notification to `#oss-nrn-monitoring-production`
71 | Tags: `alertType, stage, appName, release, buildTimeISO, customerRef, host, url, runtimeEngine, device, lang, level, nodejs, iframe, fileLabel, userId`
72 | - Action interval: 5mn
73 |
74 | #### Alert - Staging all events
75 |
76 | - Environment: `staging`
77 | - Name: Staging all events
78 | - When "additional triggers": `any`
79 | - A new issue is created
80 | - The event occurs
81 | - If: None
82 | - Then: Send a Slack notification to `#oss-nrn-monitoring-staging`
83 | Tags: `alertType, stage, appName, release, buildTimeISO, customerRef, host, url, runtimeEngine, device, lang, level, nodejs, iframe, fileLabel, userId`
84 | - Action interval: 5mn
85 |
86 | #### Alert - Development all events
87 |
88 | - Environment: `development`
89 | - Name: Development all events
90 | - When "additional triggers": `any`
91 | - A new issue is created
92 | - The event occurs
93 | - If: None
94 | - Then: Send a Slack notification to `#oss-nrn-monitoring-development`
95 | Tags: `alertType, stage, appName, release, buildTimeISO, customerRef, host, url, runtimeEngine, device, lang, level, nodejs, iframe, fileLabel, userId`
96 | - Action interval: 5mn
97 |
98 | #### Alert - [Prod] All events with "alertType" set
99 |
100 | - Environment: `production`
101 | - Name: [Prod] All events with "alertType" set
102 | - When "additional triggers": None
103 | - If: The event's tags match alertType is set
104 | - Then: Send a Slack notification to `#oss-nrn-monitoring-production`
105 | Tags: `alertType, stage, appName, release, buildTimeISO, customerRef, host, url, runtimeEngine, device, lang, level, nodejs, iframe, fileLabel, userId`
106 | - Action interval: 5mn
107 |
108 | #### Alert - [!Prod] All events with "alertType" set
109 |
110 | - Environment: `All environments`
111 | - Name: [!Prod] All events with "alertType" set
112 | - When "additional triggers": None
113 | - If: The event's tags match alertType is set
114 | The event's environment value doesn't contain production
115 | - Then: Send a Slack notification to `#oss-nrn-monitoring-staging`
116 | Tags: `alertType, stage, appName, release, buildTimeISO, customerRef, host, url, runtimeEngine, device, lang, level, nodejs, iframe, fileLabel, userId`
117 | - Action interval: 5mn
118 |
119 |
120 |
--------------------------------------------------------------------------------
/guides/monitoring/use-sentry.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: How to use Sentry
4 | parent: Monitoring
5 | grand_parent: Guides
6 | nav_order: 20
7 | ---
8 |
9 | # How to use Sentry
10 | {: .no_toc }
11 |
12 |
13 | Advices and "must-know" things regarding Sentry usage.
14 |
15 |
16 | {% include page-toc.md %}
17 |
18 | ---
19 |
20 | ## Using `ALERT_TYPES`
21 |
22 | NRN comes with built-in `ALERT_TYPES` for existing alerts, defined in the `sentry.ts` file.
23 |
24 | Feel free to add more alert types, they're mostly useful to help you increase the observability of your backend, by helping you to make sense of what's happening.
25 |
26 | ### Dependencies
27 |
28 | - [`@sentry/browser`](https://www.npmjs.com/package/@sentry/browser): Package to use from the browser.
29 | - [`@sentry/node`](https://www.npmjs.com/package/@sentry/node): Package to use from the server.
30 |
31 | Sentry provides 2 different packages, with different abilities (but a very similar API) for browser and server usage.
32 |
33 | #### A note about `@sentry/node` usage _(Webpack trick)_
34 |
35 | In the source code, we always use `@sentry/node`, which is automatically converted at build step by Webpack. (see `next.config.js`)
36 |
37 | This way, we always use the same import, which is linked to the right package based on the runtime engine target.
38 |
39 | ### What about `@sentry/react`?
40 |
41 | [See #164](https://github.com/UnlyEd/next-right-now/issues/164)
42 |
43 | ### Resources
44 |
45 | - [https://sentry.io/welcome/](https://sentry.io/welcome/)
46 | - [https://docs.sentry.io/](https://docs.sentry.io/)
47 | - [Official "Getting started" guide](https://docs.sentry.io/error-reporting/quickstart/?platform=javascript)
48 | - [Capturing errors](https://docs.sentry.io/error-reporting/capturing/?platform=javascript)
49 | - [Configuration](https://docs.sentry.io/error-reporting/configuration/?platform=javascript)
50 | - [Using "context" for events](https://docs.sentry.io/enriching-error-data/context/?platform=javascript)
51 | - [Using "breadcrumbs" for events](https://docs.sentry.io/enriching-error-data/breadcrumbs/?platform=javascript)
52 | - [How to blacklist sensitive data tracking (GDPR, security)](https://docs.sentry.io/data-management/sensitive-data/)
53 |
--------------------------------------------------------------------------------
/guides/online-hosting/index.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: Online hosting
4 | parent: Guides
5 | nav_order: 10
6 | has_children: true
7 | ---
8 |
9 | # About Vercel
10 |
11 | We love Vercel, and it's really a great help to deploy web apps. They basically took something very powerful but complicated like AWS and made it
12 | developer-friendly while providing a great developer experience.
13 |
14 | Although, we were a bit wary about some changes they made in April 2020 and decisions made by the Vercel team, in particular regarding
15 | their [2020 April Pricing changes](https://github.com/vercel/vercel/discussions/4029), and we led a discussion about it.
16 |
17 | Even though, they've made huge positive changes in the last 6 months of 2020, and we believe they'll take the web as we know it to yet another level.
18 |
19 | Also, Vercel is behind the Next.js framework.
20 |
21 | They recently [announced a $40M funding](https://vercel.com/blog/series-b-40m-to-build-the-next-web) Series B.
22 |
23 | ## Resources
24 |
25 | - [https://vercel.com/docs](https://vercel.com/docs)
26 | - [https://vercel.com/blog](https://vercel.com/blog)
27 | - [Join Next.js Discord server](https://discord.gg/w8p9Psrk2M)
28 |
--------------------------------------------------------------------------------
/guides/online-hosting/setup-vercel.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: How to setup Vercel
4 | parent: Online deployment
5 | grand_parent: Guides
6 | nav_order: 10
7 | ---
8 |
9 | # How to setup Vercel
10 | {: .no_toc }
11 |
12 |
13 | Step-by-step guide about how to create and properly configure your Vercel account.
14 |
15 |
16 | {% include page-toc.md %}
17 |
18 | ---
19 |
20 | ## Create your Vercel account
21 |
22 | > Creating a Vercel account is **necessary** to deploy the application online (staging/production stages) using Vercel as a hosting provider.
23 |
24 | - [Create a free account on Vercel](https://vercel.com/signup?ref=unly-nrn)
25 |
26 | ---
27 |
28 | ## Deploying on Vercel
29 |
30 | ### Pre-requisites
31 |
32 | {% include vercel-online-hosting-pre-requisites.md %}
33 | {: .mb-6 }
34 |
35 | ### Deploying on Vercel (manually)
36 |
37 | 1. `yarn start` - Will start the project locally, and create the `.vercel` folder.
38 | - Alternatively, on Windows, you need to run `yarn start:windows`
39 | 1. `yarn deploy` - Will deploy the project online, and automatically create the Vercel project first, if it doesn't exist already.
40 | This command will fail if any secret is missing.
41 | 1. Add a `scope` line in all `vercel.*.json` files using the `orgId` in `.vercel/project.json` (this folder is created when running `npx vercel`, which was called when you run the above `yarn start`)
42 | - **Tip**: Don't forget `vercel.json` is a **symlink** and **shouldn't** to be modified (run `ln vercel.staging.json vercel.json` if you messed it up :wink:)
43 | 1. `yarn deploy` - Will deploy the project online, and automatically create the Vercel project first, if it doesn't exist already
44 | 1. Go to [Vercel](https://vercel.com/) to see the project being deployed, go through logs, etc.
45 |
46 | - **Tip**: Vercel doesn't provide the `orgId` from the Vercel platform itself, even if the project exists already. Running `yarn start` locally is the only way to know what is your `orgId`, AFAIK.
47 |
48 | ---
49 |
50 | ### Deploying specific stages and tenants
51 |
52 | For each customer instance, we create a different Vercel project.
53 |
54 | A project is itself composed of multiple staging deployments (called "previews" on Vercel) and one production deployment.
55 |
56 | _**Tip**: If you want to learn more about what happens (on the technical level) when pushing a commit to the repository, read the [CI/CD section](../ci-cd)_.
57 |
58 | {: .mt-6 }
59 | ##### Staging deployments
60 |
61 | Using Vercel, **we have access to many staging "deployments"**.
62 |
63 | By default, there is one custom domain per Git Branch, but also one per commit.
64 | It is also possible to create a custom domain manually from the CLI, for any deployment.
65 |
66 | ###### When not using a `MST` preset
67 |
68 | - `yarn deploy` - Deploy the app in staging
69 |
70 | ###### When using a `MST` preset
71 |
72 | - `yarn deploy` - Deploy the customer1 app in staging (shortcut)
73 | - `yarn deploy:customer1` - Deploy the customer1 app in staging (identical to previous, shortcut)
74 | - `yarn deploy:customer2` - Deploy the customer2 app in staging
75 | - `yarn deploy:all` - Deploy all apps in staging
76 |
77 | {: .mt-6 }
78 | ##### Production deployment
79 |
80 | While there can be multiple staging deployments, **there is only one production deployment (per project)**
81 |
82 | ###### When not using a `MST` preset
83 |
84 | - `yarn deploy:production` - Deploy the app in production
85 |
86 | ###### When using a `MST` preset
87 |
88 | - `yarn deploy:customer1:production` - Deploy the customer1 app in production
89 | - `yarn deploy:customer2:production` - Deploy the customer2 app in production
90 | - `yarn deploy:all:production` - Deploy all apps in production
91 |
92 | - **Tip**: Those commands use the `vercel` command with the `--prod` argument behind the wheel.
93 | - **Tip**: Those commands are used by our CI/CD Github Actions.
94 |
95 | ---
96 |
97 | ### Configuring custom Vercel <> Github Actions integration
98 |
99 | Our automated CI/CD process basically deploys all branches as Vercel preview deployments, except for commits pushed to `main` or `master` branches, which are automatically deployed in production.
100 |
101 | {: .mt-6 }
102 | ##### How to configure Github Actions integration
103 |
104 | > This step is critical to configure GitHub Actions for your repository.
105 |
106 | See [How to setup Github Actions](../ci-cd/gha-deploy-vercel)
107 |
108 | ### Configuring Vercel secrets (manually)
109 |
110 | This documentation is in-case-of you'd need to configure secrets through the CLI
111 |
112 | - Each secret must be added manually, one by one
113 | - A secret starts with `@`
114 | - Secrets are global to the whole team, that's why they're all prefixed by `nrn-`, so that they don't conflict with other projects
115 | - Take a look at `.env.example` for secrets to use by default _(you can use them for testing purpose, it's fine, they're not sensitive)_
116 | - Example: `vercel secrets add nrn-locize-project-id 658fc999-dfa8-4307-b9d7-b4870ad5b968`
117 |
118 | - **Tip**: If any secret is not set, the app will fail to deploy. The Vercel CLI will complain about missing secrets and abort the build.
119 |
120 | ### Configuring Vercel deployment regions
121 |
122 | You may want to deploy Vercel to multiple regions in the world, depending on your use case
123 |
124 | By default (if not specified), NRN tries to deploy to all regions (see `vercel.*.json:regions`), but this will only be effective if you are under a Vercel plan that allows it.
125 |
126 | Please see the [official documentation](https://vercel.com/docs/v2/network/regions-and-providers#routing).
127 |
128 | - **Tip**: Note that this is an advanced feature which requires a paying account, it's not available for free.
129 |
--------------------------------------------------------------------------------
/guides/online-hosting/use-vercel.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: How to use Vercel
4 | parent: Online deployment
5 | grand_parent: Guides
6 | nav_order: 20
7 | ---
8 |
9 | # How to use Vercel
10 | {: .no_toc }
11 |
12 | {% include page-toc.md %}
13 |
14 | ---
15 |
16 | ## Node.js runtime version
17 |
18 | Note that your code will be deployed on Vercel servers, which are running under **AWS Lambda** on the background.
19 |
20 | - By default, Vercel will deploy using Node.js `v12.x` runtime, the `x` means it will automatically use the latest version. _(This is still true as of January, 2021)_
21 | - This means that you should update your `.nvmrc` to match the version that's actually being used by Vercel, from time to time. It's not really a big deal as long as there is a minor version difference, but make sure to use the same major version to avoid "surprises".
22 | - See [official Vercel Node.js supported versions](https://vercel.com/docs/runtimes#official-runtimes/node-js/node-js-version)
23 | - See [available AWS Lambda runtimes](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html), it may be interesting for reference, and it's important to understand what really runs your source code. Vercel is just a proxy that simplifies things.
24 | - We provide a built-in utility you can use on any online demo at `/api/status`, for instance at [https://nrn-default.now.sh/api/status](https://nrn-default.now.sh/api/status).
25 | - You can also use this endpoint locally, or on your own deployments.
26 | - **Tip**: As a security measure, you may want to either disable or protect that endpoint, using Basic-Auth for instance.
27 |
28 | > Node.js v12 will reach EOL as of April 2022. [Source](https://nodejs.org/en/about/releases/)
29 | >
30 | > By experience, we expect AWS to upgrade the Node.js runtime to allow the use of Node.js v14 around Q2 2021. Vercel will most likely quickly follow.
31 | >
32 | > AWS Lambda usually allows the next Node.js LTS version every year around April, and deprecates the latest EOL version around the same time.
33 | >
34 | > You should consider this, as it might affect you when picking libraries, as they will need to be compatible (or maintained) with the upcoming Node.js version.
35 | > It is usually not an issue, but we personally ran into troubles with unmaintained binaries (like Dialogflow) in 2018, when we were using AWS Lambda directly (without Vercel).
36 | >
37 | > Using Vercel, we didn't run into any Node.js upgrade issue since 2019. All went smoothly, we expect the upgrade to Node.js 14 to be smooth as well.
38 |
39 | ## Resources
40 |
41 | - [https://vercel.com/docs](https://vercel.com/docs)
42 | - [https://vercel.com/blog](https://vercel.com/blog)
43 | - [Join Next.js Discord server](https://discord.gg/w8p9Psrk2M)
44 |
--------------------------------------------------------------------------------
/guides/stacker-cms/index.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: Stacker CMS
4 | parent: Guides
5 | nav_order: 90
6 | has_children: true
7 | ---
8 |
9 |
10 |
11 | Stacker lets you create the digital tools you need to engage your customers, partners and team, all powered by the data in your Airtable or Google Sheets.
12 |
13 |
14 |
15 | ---
16 |
17 | # About Stacker
18 |
19 | [Stacker](https://stacker.app/?ref=unly-nrn) is a very flexible way to build your own Back Office, CRM, or any admin tool, whether internal, external, or both.
20 |
21 | > At Unly, we use it to manage our customers using a UI we built ourselves (no-code), while allowing our customers to manage their own content, using a UI we built specifically for them.
22 | >
23 | > Back in early 2020, we spent a few months testing various solutions (Strapi, Directus, GraphCMS, etc.) of "Headless CMS".
24 | >
25 | > After much intense testing, we selected Stacker as our back-office software partly because **it's the most flexible tool we had found**.
26 |
27 | ## Stacker Demo with Next Right Now
28 |
29 | Open the [NRN Demo](https://nrn-v2-mst-aptd-at-lcz-sty-c1.vercel.app) to learn more.
30 |
31 | [Impersonate a Stacker user](https://nrn.my.stacker.app/login?api_token=be1050d1-de5e-4ae0-97c8-030a132f254b&ref=unly-nrn) to see what our homemade Stacker-UI allows you to do as an Editor, and visit the [NRN Demo (with preview mode)](https://nrn-v2-mst-aptd-at-lcz-sty-c1-preview.vercel.app) to see changes live.
32 |
--------------------------------------------------------------------------------
/guides/stacker-cms/setup-stacker.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: How to setup Stacker
4 | parent: Stacker CMS
5 | grand_parent: Guides
6 | nav_order: 10
7 | ---
8 |
9 | # How to setup Stacker
10 | {: .no_toc }
11 |
12 |
13 | Step-by-step guide about how to create and properly configure your Stacker account.
14 |
15 |
16 | {% include page-toc.md %}
17 |
18 | ---
19 |
20 | ## Tips
21 |
22 | You can get your first month for free using the [`nrn1m` coupon code](https://studio.airportal.app/register?coupon=nrn1m). Note that Stacker is free until you deploy your app to production and start having customers using it.
23 |
24 | If you want to build a POC, it's a great opportunity!
25 |
26 | ---
27 |
28 | ## Create Stacker account
29 |
30 | - [Create a free account on Stacker](https://studio.airportal.app/register?coupon=nrn1m)
31 | - Select which database you want to use, you can use either Airtable, Google Sheets or SalesForce
32 | - My advice is to go with Airtable if you're just playing around or don't intend to have more than 1.2k records (it's free up to that limit).
33 | - If you're interested about Airtable, [here is how to get $2k credits for $50](https://www.joinsecret.com/fr/offers/airtable-coupon-1800) (We've personally used it!).
34 | - Google sheets may be a more viable option if you intend to have tons of rows in your DB.
35 |
36 |
--------------------------------------------------------------------------------
/guides/stacker-cms/use-stacker.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: How to use Stacker
4 | parent: Stacker CMS
5 | grand_parent: Guides
6 | nav_order: 20
7 | ---
8 |
9 | # How to use Stacker
10 | {: .no_toc }
11 |
12 |
13 | Advices and "must-know" things regarding Stacker usage.
14 |
15 |
16 | {% include page-toc.md %}
17 |
18 | ---
19 |
20 | ## Usage
21 |
22 | We won't cover how to use Stacker in this documentation.
23 | Please refer to their [official documentation](https://docs.stacker.app/?ref=unly-nrn).
24 |
25 | ## Slack Support
26 |
27 | [Join their Slack channel](https://stacker-customers.slack.com) for getting proper support. _(they're awesome and very helpful, even for free customers!)_
28 |
29 |
30 |
31 |
--------------------------------------------------------------------------------
/guides/storybook/index.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: Storybook
4 | parent: Guides
5 | nav_order: 1
6 | has_children: true
7 | ---
8 |
9 |
10 |
11 | Storybook is an open source tool for developing UI components in isolation for React, and more. It makes building stunning UIs organized and efficient.
12 |
13 |
14 |
15 | ---
16 |
17 | # About Storybook
18 |
19 | [Storybook](https://storybook.js.org/?ref=unly-nrn) helps you build an interactive documentation of your UI components.
20 |
21 | > Next Right Now [uses Storybook](https://nrn-v2-mst-aptd-at-lcz-sty-storybook.vercel.app/){:target="_blank"} to host its own components.
22 | >
23 | > Each preset has its own dedicated Storybook, with components specific to the preset.
24 | >
25 | > When you use Next Right Now as a boilerplate, you automatically benefit from a default Storybook setup, which was designed to be extended, so you can include your own components.
26 |
27 | The documentation about all the Next Right Now React components is done on Storybook.
28 |
29 | > At this time, Storybook only has one "production" static site, there is no staging. It didn't seem necessary to make things more complicated, as it's not supposedly to be critical.
30 |
--------------------------------------------------------------------------------
/guides/storybook/setup-storybook.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: How to setup Storybook
4 | parent: Storybook
5 | grand_parent: Guides
6 | nav_order: 10
7 | ---
8 |
9 | # How to setup Storybook
10 | {: .no_toc }
11 |
12 |
13 | Step-by-step guide about how to properly configure your own Storybook.
14 |
15 |
16 | {% include page-toc.md %}
17 |
18 | ---
19 |
20 | ## Configuring Vercel
21 |
22 | Storybook is hosted on Vercel. It uses a dedicated deployment file `vercel.storybook.json`.
23 |
24 | Within that file, you'll need to change the `name`, `scope` and `alias`.
25 |
26 | > By default, those are NRN's, and you won't be allowed to deploy your Storybook site onto NRN's Vercel account.
27 |
28 | - The `name` is the Vercel project name you want to use, (it'll be created automatically on Vercel).
29 | - The `scope` is your Vercel personal or team ID. You can find it as `orgId` in `.vercel/project.json`. If the `.vercel` folder doesn't exist yet, it's because you haven't run `yarn start` yet.
30 | - The `alias` will be used by the Github Actions workflow to automatically alias the deployment.
31 |
32 | ## Configuring Cypress
33 |
34 | Storybook is being tested using Cypress to make sure you don't break the whole production static site unknowingly.
35 |
36 | > This Cypress test is not meant to test all components, we wrote tests for the `Btn` component and that's it. The goal is to detect fatal failures, so testing only one component is enough.
37 | >
38 | > Alternatively, if you wish to write your Components tests using Cypress this way, it's possible, but not the recommended way. It's much lighter/faster to write Cypress tests for components directly, without going through Storybook.
39 |
40 | The Cypress configuration for Storybook uses a dedicated config file at `cypress/config-storybook.json`.
41 |
42 | > We decided to use the same `cypress/` folder for all Cypress configuration, because using another folder would lead to complicating the webpack/babel config. It seemed easier this way.
43 |
44 | Unless you use Cypress Dashboard feature, you don't have anything to change in `cypress/config-storybook.json`,
45 | because Cypress is automatically executed on the Vercel deployment url, not the alias domain.
46 |
47 | > If you use Cypress Dashboard feature, you'll need to change the `projectId` [accordingly](../testing/setup-cypress/#cypress-plans-and-pricing).
48 |
49 | ## Configuring Google Analytics
50 |
51 | The Storybook static site has built-in analytics using the [`google-analytics` addon](https://github.com/storybookjs/storybook/tree/master/addons/google-analytics){:target="_blank"}.
52 |
53 | > We decided to use Google Analytics instead of Amplitude for Storybook, because all the work has been done by other people, it's been done well, and we don't need the flexibility/complexity of Amplitude for the Storybook site.
54 |
55 | You'll need to replace the `STORYBOOK_GA_ID` in `.storybook/manager.js`. (otherwise, you'll send your analytics events to us!)
56 |
57 |
--------------------------------------------------------------------------------
/guides/storybook/use-storybook.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: How to use Storybook
4 | parent: Storybook
5 | grand_parent: Guides
6 | nav_order: 20
7 | ---
8 |
9 | # How to use Stacker
10 | {: .no_toc }
11 |
12 |
13 | Advices and "must-know" things regarding Storybook usage.
14 |
15 |
16 | {% include page-toc.md %}
17 |
18 | ---
19 |
20 | ## Usage
21 |
22 | We won't cover how to write your own Storybook "Stories" in this documentation.
23 | Please refer to their [official documentation](https://storybook.js.org/?ref=unly-nrn).
24 |
25 | > If you need support, check out [their Support page](https://storybook.js.org/support/), they have a Discord channel.
26 |
27 | ### Working locally
28 |
29 | Run `yarn storybook` (or `yarn sb` for short).
30 |
31 | This will start the Storybook site on your computer, and automatically open it on the browser.
32 |
33 | You can edit your components and see changes go live. You can also add Storybook Stories (in `src/stories`) to preview different Stories for each component.
34 |
35 | ### Online site (Vercel)
36 |
37 | When you push some code on GitHub, the `.github/workflows/deploy-vercel-storybook.yml` is automatically triggered and will build a static version of the
38 | Storybook site, and then host it on Vercel.
39 |
40 | The static site will be deployed at the domain(s) specified by `vercel.storybook.json`.
41 |
42 | ### Deploying the static site manually
43 |
44 | Although everything is automated, you can also deploy your static site manually by running:
45 | - `yarn deploy:sb:gha` Exports the static site (into `storybook-static` folder) and deploy it to Vercel. (It's the command being called by GitHub Actions)
46 | - `yarn deploy:sb:gha:fast` Deploys the `storybook-static` folder (doesn't build), useful if you've already exported the site (faster)
47 |
48 | ## Package maintenance
49 |
50 | ### Upgrading all Storybook packages at once
51 |
52 | Run `yarn sb:upgrade`, this makes sure you use the same version for all packages (e.g: react, addons `@storybook/*`), which is strongly recommended by officials.
53 |
--------------------------------------------------------------------------------
/guides/tenancy/index.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: Tenancy
4 | parent: Guides
5 | nav_order: 110
6 | has_children: true
7 | ---
8 |
9 |
14 |
15 | ---
16 |
17 | ## Overview
18 |
19 | > This is an explanation guide about how the NRN tenancy system works.
20 |
21 | The tenancy system affects a very small part of the whole source code, but it's critical to get it right nonetheless because that's one of the main thing on what everything else relies on.
22 |
23 | ### Parts of the NRN app strongly affected by the MST tenancy design
24 |
25 | The MST design is the most complex of all tenancy designs that is currently available on NRN.
26 | It's very useful for managing a fleet of customers, but it comes at the price of increased complexity.
27 |
28 | - `MST` makes the CI/CD much more complicated, because it needs to handle the deployment of different "customers".
29 | - The Vercel configuration is more difficult too, because:
30 | - Each tenant (customer) has its own set of Vercel configuration (`vercel.customer1.*.json`, etc.).
31 | - Each tenant might have its own `secrets` and ENV variables.
32 | - Each tenant is managed through a distinct Vercel project on [https://vercel.com/](https://vercel.com/).
33 | - Each tenant is completely separated from the others, and this can complicate your app even more, depending on what other tools you rely on (DB, etc.).
34 | - The Cypress configuration is more difficult too, because:
35 | - Artifacts (videos, screenshots) must be separated between customers, otherwise it might confuse the developers during debug.
36 | - Cypress must run on the right deployment , not on the deployment of another customer.
37 |
38 | For instance, when we deploy a customer, we automatically run tests for this customer only. Other customers aren't affected.
39 |
--------------------------------------------------------------------------------
/guides/tenancy/remove-MST.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: Remove MST
4 | parent: Tenancy
5 | grand_parent: Guides
6 | nav_order: 10
7 | ---
8 |
9 | # How to remove MST tenancy design
10 | {: .no_toc }
11 |
12 |
13 | Guide about how to remove the Multi Single Tenancy feature, to use only one tenant instead.
14 |
15 |
16 | ---
17 |
18 | ## About the Multi Single Tenancy (MST)
19 |
20 | Right now, NRN only provides a MST design because [that's just easier to maintain than several tenancy models](https://github.com/UnlyEd/next-right-now/issues/151#issuecomment-683463185).
21 |
22 | Long story short, if you find yourself using a preset with MST design built-in, but don't have any use for it, you can:
23 | - Keep it and only use one tenant. The impact would be very small, it will definitely work properly, even though you only use one tenant.
24 | - Remove the MST feature manually.
25 | - _I don't advise anybody not familiar with the NRN source code doing that, it's not super-complicated, but you need to understand what happens on Vercel and Github Actions quite well._
26 |
27 | Also, if you think you might use it someday, then better to keep it for now then, because it's much harder to configure it properly than to remove it.
28 |
29 | ## Step-by-step guide
30 |
31 | Removing MST is fairly simple, when you know what you're looking for :wink:.
32 |
33 | - Only keep one deployment file per environment (e.g: `vercel.staging.json` instead of `vercel.customer1.staging.json`).
34 | - Remove all unnecessary scripts related to "customer2".
35 | - Do a full search of the project looking for `customer2`, that will tell you where to look for stuff related to MST.
36 | - Do a full search of the project looking for `NEXT_PUBLIC_CUSTOMER_REF`, that will tell you where to look for stuff related to MST, you can remove that ENV variable.
37 | - Cypress (E2E)
38 | - Rename `cypress/videos/customer1` by `cypress/videos/production` and update `e2e` scripts to use `CYPRESS_STAGE=production` instead.
39 | - You basically need to have a `videos/production` folder to store videos artifacts when E2E tests are executed manually through CLI.
40 | - Same applies to the `cypress/screenshots` folder.
41 | - Similarly, the `cypress/config*.json` files should be updated.
42 | - Update the Github Actions scripts in `.github/workflows` to make sure the E2E tests use the proper JSON file (`run-2e2-tests` action)
43 | - You'll need to update the GHA deployment scripts to run the proper deployment command (ignoring stuff related to the customer)
44 | - Basically, stuff like this
45 | - `yarn deploy:$(cat vercel.json | jq -r '.build.env.NEXT_PUBLIC_CUSTOMER_REF'):production:simple --token $VERCEL_TOKEN`
46 | - should become
47 | - `yarn deploy:production:simple --token $VERCEL_TOKEN`
48 |
49 | That should be all, make sure to do things step by step (GHA, then E2E, etc.) and things in between because it's likely to break things if you're not careful.
50 |
--------------------------------------------------------------------------------
/guides/testing/index.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: Testing
4 | parent: Guides
5 | nav_order: 70
6 | has_children: true
7 | ---
8 |
9 |
14 |
15 | ---
16 |
17 | # Jest
18 |
19 | [Jest](https://jestjs.io/) is our test runner, it runs our tests to make sure we don't ship regressions to our end users.
20 |
21 | > Jest is mostly aimed at unit testing, component testing and integration testing.
22 |
23 | ---
24 |
25 | # Cypress
26 |
27 | [Cypress]() is our end-to-end (E2E) test runner, it runs e2e tests to make sure our UI and user workflows work as expected.
28 |
29 | > Cypress is only aimed at end-to-end testing. It is automatically executed through CI/CD by GitHub Actions, and runs E2E tests against the real application, hosted on Vercel.
30 |
--------------------------------------------------------------------------------
/guides/testing/setup-cypress.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: How to setup Cypress
4 | parent: Testing
5 | grand_parent: Guides
6 | nav_order: 10
7 | ---
8 |
9 | # Cypress configuration
10 | {: .no_toc }
11 |
12 |
13 | Explanations about how Cypress is configured by Next Right Now, and how you can extend the default configuration.
14 |
15 |
16 | {% include page-toc.md %}
17 |
18 | ---
19 |
20 | ## When using MST tenancy
21 |
22 | When you're using a MST tenancy, you will have one Cypress config file per tenant, because each tenant has its own dedicated production app and domain.
23 | There is also another config file for development usage (local).
24 |
25 | Update `cypress/config-*.json` and update the `baseUrl` so that it matches with their respective production url.
26 |
27 | ## When not using MST tenancy
28 |
29 | When you're **not using** a MST tenancy, you will only have one Cypress config file.
30 | There is also another config file for development usage (local).
31 |
32 | Update `cypress/config-production.json` and update the `baseUrl` so that it matches the project's production url.
33 |
34 | # Cypress plans and pricing
35 |
36 | Next Right Now doesn't use a paid version of Cypress (no Dashboard available).
37 | We don't use their infrastructure to host our tests, since they're executed on GitHub Actions.
38 |
39 | Therefore, you don't have to pay for Cypress.
40 |
41 | But, if you wish to benefit from the [Cypress Dashboard](https://www.cypress.io/dashboard) and store your Cypress recordings then you might be interested in buying a [Cypress plan](https://www.cypress.io/pricing/).
42 |
43 | > If you buy a plan, you should **set the `orgId`** in all your `cypress/config-*.json` so that recordings will be stored on your Cypress account, and can then be accessed through the Dashboard.
44 | >
45 | > Alternatively, you could also add it only to `cypress/config-customer-ci-cd.json` if you only wish to track recordings performed through CI/CD, but not the local runs.
46 |
--------------------------------------------------------------------------------
/guides/testing/setup-jest.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: How to setup Jest
4 | parent: Testing
5 | grand_parent: Guides
6 | nav_order: 30
7 | ---
8 |
9 | # Jest configuration
10 | {: .no_toc }
11 |
12 |
13 | Explanations about how Jest is configured by Next Right Now, and how you can extend the default configuration.
14 |
15 |
16 | {% include page-toc.md %}
17 |
18 | ---
19 |
20 | ## jest-extended
21 |
22 | We extended jest with various additional assertions.
23 |
24 | See [https://github.com/jest-community/jest-extended](https://github.com/jest-community/jest-extended)
25 |
26 | ## jest-expect-message
27 |
28 | We extended jest to add custom messages to Jest `expects`.
29 |
30 | See [https://www.npmjs.com/package/jest-expect-message](https://www.npmjs.com/package/jest-expect-message)
31 |
32 | ## How is Jest configured?
33 |
34 | The `jest.config.js` contains all the Jest configuration, including:
35 |
36 | - TypeScript's configuration (so that Jest can run `.ts` files)
37 | - A dedicated `tsconfig.jest.json` is used when running TS files (which inherits from the `jest.config.json` configuration)
38 | - Built-in extra configuration, using `setupFilesAfterEnv`:
39 | - `jest-extended` (see above)
40 | - `jest-expect-message` (see above)
41 | - `jest.setup.js`, which configure Jest globally, such as:
42 | - Imports `.env.local` and `.env` files (`.env.local` takes precedence when env variable clash)
43 | - Imports Next.js polyfills (such as `fetch`)
44 | - Provides utilities such as `muteConsole`, `muteConsoleButLog` and `unmuteConsole` for logging
45 | - `jest.extends.js`, which extends Jest `expect` function globally, with:
46 | - `toContainObject`
47 | - `toMatchOneOf` from [jest-to-match-shape-of](https://www.npmjs.com/package/jest-to-match-shape-of)
48 | - `toMatchShapeOf` from [jest-to-match-shape-of](https://www.npmjs.com/package/jest-to-match-shape-of)
49 | - Built-in extra configuration, using a custom `runner` with [`jest-runner-groups`](https://github.com/eugene-manuilov/jest-runner-groups):
50 | - It allows you to run a bunch of test together (AKA a "group").
51 | - This is very useful to run, or exclude a group of files from a test run.
52 | - A few groups already exists, such as `api`, `components`, `integration`, `unit`, `utils` and have a dedicated NPM script (e.g: `yarn test:group:unit`)
53 | - For instance, the tests executed by Vercel when deploying a new domain do not run the `integration` tests, as they take a long time to run, and too often fail due to network, or I/O-related false-positive issues.
54 |
55 | ## How to extend Jest?
56 |
57 | - If you wish to change the Jest configuration globally, you should do so in `jest.setup.js`.
58 | - If you wish to extend the Jest configuration to enhance the `expect` function, you can either:
59 | - Do so in `jest.config.json` at `setupFilesAfterEnv`, if the library is meant to be configured in such a way (such as `jest-extended`).
60 | - Alternatively, do so in `jest.extends.js`.
61 |
62 |
--------------------------------------------------------------------------------
/guides/testing/use-cypress.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: How to use Cypress
4 | parent: Testing
5 | grand_parent: Guides
6 | nav_order: 20
7 | ---
8 |
9 | # How to use Cypress
10 | {: .no_toc }
11 |
12 |
13 | Advices and "must-know" things regarding Cypress usage.
14 |
15 |
16 | {% include page-toc.md %}
17 |
18 | ---
19 |
20 | ## Overview
21 |
22 | Cypress is a tool that helps performing end-to-end (E2E) tests that aim at testing the UI and the user workflows.
23 |
24 | It is open source and free to use from the command line (doesn't count as Tests recording).
25 |
26 | Several utility scripts have been configured to help with E2E testing, each script takes an optional `CYPRESS_STAGE` environment variable, which defines the config file (in `cypress/`) that will be used (`development` by default):
27 | - `yarn e2e:open`: Runs the test suite in a local **browser**
28 | - Requires Cypress to be installed first using `yarn e2e:install`
29 | - Targets **localhost development website**. (uses `cypress/config-development.json`)
30 | - `yarn e2e:run`: Runs the test suite in a local **console**
31 | - Targets **localhost development website**. (uses `cypress/config-development.json`)
32 |
33 | It is also possible to test all the apps at once:
34 | - `yarn e2e:all:production`: This will run each production e2e test run (in series, parallel is not free)
35 |
36 | We used the following [**Cypress <> Next.js** tutorial](https://buttercms.com/blog/how-to-test-nextjs-apps) to get started.
37 |
38 | Note that our current installation doesn't provide test coverage.
39 | It's a bit harder to setup, here is a [tutorial](https://www.cypress.io/blog/2019/09/05/cypress-code-coverage-for-create-react-app-v3/) if ever needed.
40 |
41 | - **Tip**: [Here is the documentation about the options available in the config files](https://docs.cypress.io/guides/references/configuration.html).
42 |
43 | ## Resources
44 |
45 | - [https://www.cypress.io/](https://www.cypress.io/)
46 | - [https://docs.cypress.io/guides/overview/key-differences.html#Architecture](https://docs.cypress.io/guides/overview/key-differences.html#Architecture)
47 |
--------------------------------------------------------------------------------
/guides/testing/use-jest.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: How to use Jest
4 | parent: Testing
5 | grand_parent: Guides
6 | nav_order: 40
7 | ---
8 |
9 | # How to use Jest
10 | {: .no_toc }
11 |
12 |
13 | Advices and "must-know" things regarding Jest usage.
14 |
15 |
16 | {% include page-toc.md %}
17 |
18 | ---
19 |
20 | ## Local usage
21 |
22 | Local usage is meant to be used through the built-in scripts, as described below.
23 |
24 | ## CI/CD usage (Vercel)
25 |
26 | Tests are automatically executed by Vercel during the deployment, in the `build` script, from `package.json`.
27 |
28 | ```json
29 | {
30 | "scripts": {
31 | "build": "yarn test:once:group:no-integration && next build"
32 | }
33 | }
34 | ```
35 |
36 | If the tests fail, the build is aborted and nothing will be deployed.
37 |
38 | ## Scripts
39 |
40 | There are a few available scripts you can use right away, from `package.json`:
41 | - `yarn test`: Runs all tests in watch mode, runs tests for changed files only by default.
42 | - `yarn test:group:api`: Runs tests tagged with the "api" group.
43 | - `yarn test:group:components`: Runs tests tagged with the "components" group.
44 | - `yarn test:group:integration`: Runs tests tagged with the "integration" group. Usually, integration test are meant to test external APIs or perform network requests, which makes them slow.
45 | - `yarn test:group:unit`: Runs tests tagged with the "unit" group.
46 | - `yarn test:group:utils`: Runs tests tagged with the "utils" group.
47 | - `yarn test:once`: Run all tests, once. (no watcher) Used in CI/CD.
48 | - `yarn test:once:group:no-integration`: Run all tests, once, except those tagged with the "integration" group. Used in CI/CD.
49 | - `yarn test:coverage`: Run all tests, with coverage.
50 | - `yarn test:coverage:group:no-integration`: Run all tests, with coverage, except those tagged with the "integration" group.
51 | - `yarn test:config`: Prints the Jest configuration, quite useful for debugging Jest misconfiguration.
52 |
53 | > Feel free to add more groups to your liking, the above is simply a good place to start, but the only limit is your imagination!
54 |
55 | ## Write tests
56 |
57 | > We won't cover this section in-depth, you should refer to the official [`jest`](https://jestjs.io/) documentation.
58 |
59 | Also, we strongly recommend you to take a look at how Next Right Now tests are written.
60 | Look for `*.test.ts` files
61 |
62 | ## Dependencies
63 |
64 | - [`jest`](https://www.npmjs.com/package/jest): Jest is a delightful JavaScript Testing Framework with a focus on simplicity.
65 | - [`jest-extended`](https://www.npmjs.com/package/jest-extended): Additional Jest matchers. Provides additional built-in tests for ease of testing.
66 | - [`react-test-renderer`](https://www.npmjs.com/package/react-test-renderer): This package provides an experimental React renderer that can be used to render React components to pure JavaScript objects, without depending on the DOM or a native mobile environment.
67 | Essentially, this package makes it easy to grab a snapshot of the "DOM tree" rendered by a React DOM or React Native component without using a browser or jsdom.
68 | - [`ts-jest`](https://www.npmjs.com/package/ts-jest): TypeScript preprocessor with source map support for Jest that lets you use Jest to test projects written in TypeScript.
69 | - [`jest-to-match-shape-of`](https://www.npmjs.com/package/jest-to-match-shape-of): A Jest matcher to verify the structure of an object, particularly useful for api integration tests.
70 | - [`jest-runner-groups`](https://github.com/eugene-manuilov/jest-runner-groups): A test runner that allows you to tag your tests and execute specific groups of tests with Jest.
71 |
72 | **Known issues**:
73 | - `jest-emotion`: [Breaks tests](https://github.com/emotion-js/emotion/issues/1440#issuecomment-551235747)
74 |
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "next-right-now-docs",
3 | "version": "1.0.0",
4 | "private": true,
5 | "scripts": {
6 | "start": "yarn doc:start",
7 | "start:fast": "yarn doc:start:fast",
8 | "preversion": "yarn lint:once && yarn test:once",
9 | "release": "yarn bump --commit --tag && git add CHANGELOG.md README.md && git commit --amend --no-edit && git push && git push --tags",
10 | "doc:start": "bundle exec jekyll serve --config _config-development.yml",
11 | "doc:start:fast": "bundle exec jekyll serve --config _config-development.yml --incremental",
12 | "doc:gem:install": "bundle install",
13 | "security:audit": "yarn audit",
14 | "packages:upgrade": "yarn upgrade-interactive --latest"
15 | },
16 | "devDependencies": {
17 | "concurrently": "5.2.0",
18 | "cross-env": "7.0.2",
19 | "del-cli": "3.0.1",
20 | "version-bump-prompt": "6.0.3"
21 | }
22 | }
23 |
--------------------------------------------------------------------------------
/reference/demo-database-structure.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: Demo DB structure
4 | parent: Reference
5 | nav_order: 30
6 | ---
7 |
8 | # Demo database structure
9 | {: .no_toc }
10 |
11 | {% include page-toc.md %}
12 |
13 | ---
14 |
15 | ## Airtable vendor
16 |
17 | > Data structure of the Airtable database used as example.
18 | >
19 | > This is useful if you wish to understand the relationships and data structure of the demo.
20 | >
21 | > You can "Copy base" (top right) if you wish to quickly duplicate the base to make it your own.
22 | > It can be a good starting point if you're using Next Right Now as a boilerplate for your own project!
23 |
24 | [See Base configuration](https://airtable.com/shrnxN46JDBkQV9u1)
25 |
26 | ## GraphCMS vendor
27 |
28 | > Data structure of the GraphCMS database used as example.
29 | >
30 | > This is useful if you wish to understand the relationships and data structure of the demo.
31 | >
32 | > It's useful if try to rebuild the demo on your own GraphCMS endpoint (after cloning, for example).
33 |
34 | - customer
35 | - ref - Single line text, required, unique
36 | - label - Single line text, localized
37 | - theme - Theme
38 | - products - Product[]
39 | - terms - RichText Editor, localized
40 | - product
41 | - title - Single line text, required, localised
42 | - images - Asset[]
43 | - description - Markdown, localized
44 | - customer - Customer
45 | - price - float
46 | - theme
47 | - primaryColor - Single line text, required
48 | - logo - Asset, required
49 | - customer - Customer
50 |
--------------------------------------------------------------------------------
/reference/github-environments.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: GitHub environments and deployments
4 | parent: Reference
5 | nav_order: 80
6 | ---
7 |
8 | # GitHub environments and deployments
9 | {: .no_toc }
10 |
11 |
12 | GitHub deployments help display a history of your deployments. They don't perform the actual deployments (Vercel does), but simply keep a trace of it.
13 |
14 |
15 | ---
16 |
17 | ## Introduction to GitHub deployments
18 |
19 | [Official documentation](https://docs.github.com/en/rest/reference/repos#deployments)
20 |
21 | ## GitHub Deployment with Next Right Now
22 |
23 | Next Right Now integrates GitHub Deployments since [v5.0.7 (January 2021)](https://github.com/UnlyEd/next-right-now/issues/280) to help keep track of what deployments are sent to Vercel.
24 |
25 | They are not meant to replace the Vercel dashboard, but to complementary.
26 |
27 | > At Unly, they're useful to our Customer Success and Support teams, so they can keep track of a customer's deployment history without developers' assistance.
28 |
29 | > For Next Right Now, they're useful to visitor looking for the deployment history of a demo customer, because they don't have access to the Vercel deployment history.
30 |
--------------------------------------------------------------------------------
/reference/index.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: Reference
4 | nav_order: 50
5 | has_children: true
6 | ---
7 |
8 | # Reference
9 |
10 |
--------------------------------------------------------------------------------
/reference/module-path-aliases.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: Module path aliases
4 | parent: Reference
5 | nav_order: 25
6 | ---
7 |
8 | # Module paths aliasing
9 |
10 |
11 | Understanding what is "module path aliases", why to use it and how to change it.
12 |
13 |
14 | ---
15 |
16 | ## What are "module path aliases"?
17 |
18 | > We redacted [an article](https://dev.to/vadorequest/migrating-next-js-jest-storybook-cypress-to-use-module-path-aliases-instead-of-relative-paths-d9a) about "why" we decided to use module path aliases.
19 |
20 | Module path aliases [are supported by Next.js since v9.4](https://nextjs.org/docs/advanced-features/module-path-aliases).
21 |
22 | ## Module path aliases in Next Right Now
23 |
24 | Next Right Now has introduced module path aliases as part of the huge refactoring of the folder structure on January 20, 2021:
25 | - [See "Use module path aliases" #265 PR](https://github.com/UnlyEd/next-right-now/pull/265)
26 | - [See "(MAJOR) Massive folder structure refactoring (`v2-mst-aptd-at-lcz-sty`), using modular approach and module path aliases" PR](https://github.com/UnlyEd/next-right-now/pull/264)
27 |
28 | ### How/where are configured module path aliases?
29 |
30 | The following path aliases have been configured thorough the whole app (at 7 different places). They're used in
31 |
32 | - `tsconfig.json`
33 | - `cypress/tsconfig.json`
34 | - `.storybook/jsconfig.json`
35 | - `cypress/jsconfig.json`
36 | - `.storybook/main.js:webpackFinal`
37 | - `jest.config.js:moduleNameMapper`
38 |
39 | For instance, here's what contains `/tsconfig.json`:
40 | ```json
41 | {
42 | "@/app/*": [
43 | "src/app/*"
44 | ],
45 | "@/common/*": [
46 | "src/common/*"
47 | ],
48 | "@/components/*": [
49 | "src/common/components/*"
50 | ],
51 | "@/utils/*": [
52 | "src/common/utils/*"
53 | ],
54 | "@/layouts/*": [
55 | "src/layouts/*"
56 | ],
57 | "@/modules/*": [
58 | "src/modules/*"
59 | ],
60 | "@/pages/*": [
61 | "src/pages/*"
62 | ]
63 | }
64 | ```
65 |
66 | ### How to add more module path aliases?
67 |
68 | You'll need to update all above-mentioned files to add or remove a module path alias.
69 |
70 | Additionally, if you add more tools affected by the build, they might need their own webpack/typescript/custom configuration (such as what we did for Jest, Storybook and Cypress).
71 |
--------------------------------------------------------------------------------
/reference/nextjs-tutorials.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: Next.js tutorials
4 | parent: Reference
5 | nav_order: 70
6 | ---
7 |
8 | # Next.js tutorials
9 | {: .no_toc }
10 |
11 | ---
12 |
13 | ## For beginners
14 |
15 | Next.js provides a [great tutorial](https://nextjs.org/learn/basics/create-nextjs-app) for beginners, you should definitely start there if you've never used Next.js, or if you aren't familiar with the basic concepts (API, routing, etc.)
16 |
--------------------------------------------------------------------------------
/reference/react.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: React
4 | parent: Reference
5 | nav_order: 70
6 | ---
7 |
8 | # React
9 | {: .no_toc }
10 |
11 | ---
12 |
13 | ## React cheat sheet
14 |
15 | Take a look at [this react cheat sheet](https://devhints.io/react), it contains lots of examples about many things and could be quite handy!
16 |
--------------------------------------------------------------------------------
/reference/terminology.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: Terminology
4 | parent: Reference
5 | nav_order: 10
6 | ---
7 |
8 | # Terminology
9 | {: .no_toc }
10 |
11 |
12 | Definition of terms used in NRN documentation and source code.
13 |
14 |
15 | {% include page-toc.md %}
16 |
17 | ---
18 |
19 | ## Common terms
20 |
21 | ##### SSR
22 | [Server Side Rendering](https://nextjs.org/features/server-side-rendering#benefits)
23 |
24 | ##### SSG
25 | [Static Site Generation](https://nextjs.org/blog/next-9-3#next-gen-static-site-generation-ssg-support)
26 |
27 | ##### Tenancy
28 | [Definition](https://legal-dictionary.thefreedictionary.com/tenancy): A tenancy is the occupancy or possession of land or premises by lease.
29 |
30 | :thinking: **What does that mean?** :point_right: [Read more](../concepts/tenancy)
31 |
32 | ##### ST
33 | [Single-Tenancy](https://www.liquidweb.com/kb/what-is-single-tenant-vs-multi-tenant-software/) - **Single-tenancy** (ST) is an architecture in which a **single instance** of a software application and supporting infrastructure **serves one customer** (i.e: tenant).
34 |
35 | ##### MT
36 | [Multi-Tenancy](https://www.liquidweb.com/kb/what-is-single-tenant-vs-multi-tenant-software/) - **Multi-tenancy** (MT) is an architecture in which a **single instance** of a software application **serves multiple customers** (i.e: tenants).
37 |
38 | ##### HT
39 | [Hybrid-tenancy](https://www.pega.com/insights/articles/cloud-hybrid-tenancy-replacing-single-and-multi-tenancy) - **Hybrid-tenancy** (HT) is an architecture which leverages (micro)services that are **both single and multi-tenants** to **optimize** the balance of performance, scale, and security.
40 |
41 | ##### TTM
42 | [Time to market](https://en.wikipedia.org/wiki/Time_to_market)
43 |
44 | ---
45 |
46 | ## NRN terms
47 |
48 | Those terms are specific to NRN and you're not likely to find a definition elsewhere.
49 |
50 | ##### MST
51 | **Multiple single-tenancy** (MST) is an architecture in which a **single base code** of a software application allows to **deploy multiple tenants**, each with **their own infrastructure**.
52 | The infrastructure itself **may** be **completely isolated** from other tenants (ST), or **partially shared** (HT, e.g: different servers, but same DB).
53 |
54 | > _This terminology has been defined by us, we couldn't find much resources supporting this definition._
55 |
56 | ##### [Preset](../concepts/presets)
57 | Preset of features that are built-in within. Helps to quickly get started a new project.
58 |
59 | ##### Dynamic i18n
60 | Content-related (e.g: Post title in FR + EN).
61 |
62 | ##### Static i18n
63 | Everything that isn't related to dynamic content (e.g: Site links, any content that is static and not related to dynamic data).
64 |
65 |
--------------------------------------------------------------------------------
/reference/typescript.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: TypeScript
4 | parent: Reference
5 | nav_order: 70
6 | ---
7 |
8 | # TypeScript
9 | {: .no_toc }
10 |
11 |
12 | TypeScript support is provided by the Next.js framework.
13 |
14 | We rely on it a lot, and we strongly believe it increases the quality and maintainability of any application, when used correctly.
15 |
16 |
17 | ---
18 |
19 | ## TypeScript Cheat Sheet
20 |
21 | We strongly recommend you read through [TypeScript Cheat Sheet](https://react-typescript-cheatsheet.netlify.app/docs/basic/setup), it's such a great piece of work and should help you alongside your TS journey, whether you're experimented or a beginner.
22 |
23 | > You don't need to focus on "how to configure" TS, because that's already done by NRN.
24 |
25 | Alternatively, see this summary of the most-useful TS official [built-in types](https://github.com/sindresorhus/type-fest#built-in-types) and their examples.
26 |
27 | ## Type Fest
28 |
29 | Next Right Now comes built-in with [`Type Fest`](https://github.com/sindresorhus/type-fest), a set of utilities TS types.
30 |
31 | If you feel like you're missing some TS typing capabilities, check those first!
32 |
--------------------------------------------------------------------------------
/reference/vendors.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: Vendors overview
4 | parent: Reference
5 | nav_order: 19
6 | ---
7 |
8 | # Vendors overview
9 | {: .no_toc }
10 |
11 |
12 | Comprehensive overview of all vendors available with focus on what to be aware of.
13 |
14 |
15 | {% include page-toc.md %}
16 |
17 | ---
18 |
19 | ## Key figures
20 |
21 | - Amplitude costs $54k/year once you go over free plan (1 million events/month)
22 | - Amplitude can be free in Growth plan for up to one year if you benefit from their Scholarship plan (startups and non-profit can benefit)
23 | - Locize doesn't provide a free plan but only a free trial, which makes it the only vendor here that you can't use more than 2 weeks without paying (even with very low usage)
24 | - From experience, GraphCMS is the most expensive of all those vendors as soon as you need more than the free plan (Amplitude isn't considered, completely out of league)
25 | - From experience, Locize can be quite expensive because they bill for:
26 | - Subscription fees (4.5€/month)
27 | - Total of words (0.00368€ per word/month) - 2.7k words = 10€/month (expensive IMHO)
28 | - Outstanding downloads (0.000092€ per download/month) - Cheap
29 | - Outstanding modification (0.0368€ per modification/month) - 600 updates = 22€ (expensive IMHO)
30 | - So, even if you don't make any change and don't download anything, you'll still pay for both subscription and total of words and that must be a consideration before using it.
31 | - Overall, it's a fair price for the value and TTM it brought to us.
32 |
33 | ---
34 |
35 | ## Business relationship considerations
36 |
37 | We have worked with all those vendors over months, if not years. Here is our feedback to help you consider them.
38 | - GraphCMS/Locize: Awesome people, quick to reply, helpful, very nice customer success teams. Solutions/answers are given very quickly. We just love working with them. Big kuddos to them.
39 | - Vercel: Awesome product, support is great though slower. Custom requests are not their priority if you aren't in Enterprise plan. Overall we're really glad we switched to Vercel from AWS.
40 | - Sentry: Good product, good support, not much issue with the product nor contact with their team.
41 | - Amplitude: Big business, lots of people there, you definitely feel less important than other customers, they kinda target the startup market but their plans aren't suitable for us as soon as free plan is limiting growth
42 | - Gap between free and paid is so huge, it's crazy
43 | - Their react implementation is the best we found for analytics
44 | - Overall very glad we switched from Google Analytics to Amplitude
45 | - Finding workarounds to avoid to switch plan is quite a challenge and a big waste of time
46 |
47 | ---
48 |
49 | ## Pricing overview
50 |
51 | {% include vendors/all-vendors-table.md %}
52 |
53 |
--------------------------------------------------------------------------------
/reference/videos.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: Videos
4 | parent: Reference
5 | nav_order: 50
6 | ---
7 |
8 | # Videos
9 | {: .no_toc }
10 |
11 | {% include page-toc.md %}
12 |
13 | ---
14 |
15 | ## Introduction videos
16 |
17 | - [Part 1 - Overview of Next Right Now (15 minutes)](http://youtu.be/kltkFwnFL-k?hd=1): This video features Vercel deployments, i18n, GraphCMS, Locize in-context editor, Sentry monitoring, Amplitude analytics, CI/CD Github Actions
18 | - [Part 2 - Developer Experience with Next Right Now (15 minutes)](http://youtu.be/fGlgIEeUqFg?hd=1): This video features GraphQL auto-completion and local schema update, deployment workflow, CI/CD Github Actions explanations, interactive E2E testing, GraphsCMS field creation
19 |
20 | ---
21 |
22 | ## Advanced guides
23 |
24 | - [WebStorm interactive debug mode (2 minutes)](http://youtu.be/3vbkiRAT4e8?hd=1): Guides run NRN in debug mode using WebStorm debug configuration
25 |
--------------------------------------------------------------------------------
/roadmap.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: Roadmap
4 | nav_order: 60
5 | ---
6 |
7 | # Roadmap and future improvements
8 |
9 | This page is about what we intend to do in NRN in the future. It's meant to provide a little guideline about where the project is headed and what's prioritised.
10 |
11 | > All "presets requests" are managed through [this GitHub project](https://github.com/UnlyEd/next-right-now/projects/1)
12 |
13 | - We want to release more presets, [as mentioned here](https://unlyed.github.io/next-right-now/concepts/presets#which-presets-are-being-considered)
14 | - Although it's my personal goal, and those presets would definitely be useful, it'll make my life harder since it'll mean spend more time administrating all those presets and keeping them up-to-date.
15 | - It's the main reason why I haven't focused on that so far, I can't realistically maintain 5+ presets up-to-date all the time, I'm not sure how to go about that.
16 | - This has been confirmed when we released `v2-mst-aptd-at-lcz-sty` preset, with changes being done in either presets and needed to be cherry-picked in others, sometimes with small variations.
17 | - Until now, I've focused mostly on 1-2 presets and improved them as much as I can to reduce the amount of work needed when new presets will be added.
18 | - Release [`HybridCache` current implementation](https://github.com/UnlyEd/next-right-now/pull/92) as its own NPM package (basically extract it from NRN for easier re-use in other projects)
19 | - No particular hurry, it doesn't feel like it's something requested by the community
20 | - Release [`AirtableDataset` current implementation](https://github.com/UnlyEd/next-right-now/tree/30d83e961b6267ee7704d21b70004ee167f95ff5/src/types/airtableDataset) from [#229](https://github.com/UnlyEd/next-right-now/pull/229) as its own NPM package (basically extract it from NRN for easier re-use in other projects)
21 | - No particular hurry, it doesn't feel like it's something requested by the community
22 | - Unit tests for UI components and utilities, especially for the most important ones
23 | - Feel free to pick a UI component or utility and make a PR about it (one component/utility at a time, please) if you'd like to
24 | - Integrate StoryBook
25 |
26 | Check out [this discussion](https://github.com/UnlyEd/next-right-now/discussions/137) if you want to contribute to the project! Our [contributing guide](https://unlyed.github.io/next-right-now/contributing) may be helpful as well.
27 |
--------------------------------------------------------------------------------
/sep-faq.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: "-"
4 | nav_order: 61
5 | ---
6 |
--------------------------------------------------------------------------------
/testimonials.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: default
3 | title: TESTIMONIALS
4 | nav_order: 65
5 | ---
6 |
7 | # Testimonials
8 | {: .no_toc }
9 |
10 | ---
11 |
12 | > "We initially built our app with Create React App and as our product evolves we needed to have a solid SEO.
13 | > We planned to migrate to NextJS, but it looked very time-consuming to set up everything again.
14 | > Here's come Next Right Now providing a complete boilerplate with great tools already integrated like Sentry or Locize.
15 | > TypeScript, with good typings, is the icing on the cake.
16 | > It helps us a lot to move quickly on NextJS." - [ApplyFuture](https://www.applyfuture.com/), _2020-10_
17 |
18 | ---
19 |
20 |