diff --git a/docs/_includes/installation-guide-full.md b/docs/_includes/installation-guide-full.md index a1cac1e..751adca 100644 --- a/docs/_includes/installation-guide-full.md +++ b/docs/_includes/installation-guide-full.md @@ -1,11 +1,12 @@ - This assumes you've cloned the NRN repository locally (cloning it once is enough, no need to clone it multiple times, but it may be simpler to use one clone per variant if you're trying out multiple variants locally :wink:) - This assumes you're already authenticated to Zeit (you should, if you've followed the [quick start](./quick-start), or if you're familiar with Zeit already) -1. `cp .env.build.example .env.build` - Duplicates the `.env.build.example` as `.env.build` _(`.env.build` is only used when working locally)_ +1. `cp .env.build.example .env.build` - Duplicates the `.env.build.example` as `.env.build` + - **Tip**: `.env.build` is only used when working locally 1. Create an account for all required 3rd party vendors above, and fill-in missing environment variables in your `.env.build` file -1. `nvm use` - Selects the right node.js version based on the `.nvmrc` file +1. _(Optional)_ `nvm use` - Selects the right node.js version based on the `.nvmrc` file + - **Tip**: Ignore this if you're not using [NVM](https://github.com/nvm-sh/nvm), but you should! 1. `yarn` - Installs all deps from `package.json` 1. `yarn start` - Starts the app on [http://localhost:8888/](http://localhost:8888/) -1. That's it! The project now works on your local computer, and should be identical to the online demo -{% include installation-guide-tips.md %} +That's it! The project now works on your local computer! diff --git a/docs/_includes/installation-guide-quick-start.md b/docs/_includes/installation-guide-quick-start.md index a7fa477..fe0d929 100644 --- a/docs/_includes/installation-guide-quick-start.md +++ b/docs/_includes/installation-guide-quick-start.md @@ -1,8 +1,13 @@ 1. `git clone https://github.com/UnlyEd/next-right-now.git nrn-quick-start` - Clones the boilerplate 1. `cd nrn-quick-start && git checkout v1-ssr` - Selects the variant -1. `cp .env.build.example .env.build` - Duplicates the `.env.build.example` as `.env.build` _(`.env.build` is only used when working locally)_ -1. `nvm use` - Selects the right node.js version based on the `.nvmrc` file -1. `yarn add -D now@16.7.3`, now@17+ requires to be authenticated to Zeit in order to launch the project **locally**, so you must use now@16 instead, to avoid additional setup +1. `cp .env.build.example .env.build` - Duplicates the `.env.build.example` as `.env.build` + - **Tip**: `.env.build` is only used when working locally +1. _(Optional)_ `nvm use` - Selects the right node.js version based on the `.nvmrc` file + - **Tip**: Ignore this if you're not using [NVM](https://github.com/nvm-sh/nvm), but you should! 1. `yarn` - Installs all deps from `package.json` +1. _(Optional)_ `yarn add -D now@16.7.3` - Installs an older `now` CLI that doesn't require you to have a Zeit account when working locally + - **Tip**: **You don't need to do that if you already have Zeit/Now configured on your computer** _(which may be the case if you're already familiar with Zeit)_ + - **Tip**: `now@17+` requires to be authenticated to Zeit in order to launch the project **locally**, so we recommend to use `now@16` instead in order to avoid unnecessary setup 1. `yarn start` - Starts the app on [http://localhost:8888/](http://localhost:8888/) -1. That's it! The project now works on your local computer, and should be identical to the online demo + +That's it! The project now works on your local computer! diff --git a/docs/_includes/installation-guide-tips.md b/docs/_includes/installation-guide-tips.md index d01e48f..6002f44 100644 --- a/docs/_includes/installation-guide-tips.md +++ b/docs/_includes/installation-guide-tips.md @@ -1,4 +1 @@ -- **Tip**: You can start the project in **debug mode** (built-in for WebStorm only) [by running the WebStorm "Debug" configuration in debug mode](https://youtu.be/3vbkiRAT4e8) - -- **Tip**: Configure your IDE not to index `.next` and `.now` folders as they will eat a lot of your RAM because their files are changed very frequently! - - On WebStorm, right click on the folders and select `Mark directory as > Excluded`. +- **Tip**: Using WebStorm? Check out our ["How to setup" Guide](../guides/ide/setup-webstorm) diff --git a/docs/_includes/page-toc.md b/docs/_includes/page-toc.md new file mode 100644 index 0000000..57f2d2f --- /dev/null +++ b/docs/_includes/page-toc.md @@ -0,0 +1,7 @@ +--- + +## Table of contents +{: .no_toc .text-delta } + +- TOC +{:toc} diff --git a/docs/concepts/i18n.md b/docs/concepts/i18n.md index 56b1bac..104ac8b 100644 --- a/docs/concepts/i18n.md +++ b/docs/concepts/i18n.md @@ -26,30 +26,36 @@ We will only mention i18n with NRN, not l10n. Both are very similar and can be grouped together as i18n, because l10n relies on i18n capabilities. The content displayed on NRN is translated using different ways, depending on where the translations are stored: -- Content i18n - Dynamic content, data related (i.e: Blog title in FR + EN). It will depend on your data and how you fetch those data (API, SSG, etc.) -- Platform i18n - Static content, platform related (i.e: Site links, any content that is static and not related to dynamic data). +- Dynamic i18n - Content-related (i.e: Post title in FR + EN). It will depend on your data and how you fetch those data (API, SSG, etc.) +- Static i18n - Everything that isn't related to dynamic content (i.e: Site links, any content that is static and not related to dynamic data). It will depend on how you fetch those data (vendor (API), i18n static files, etc.) -It is possible, although very rare, to use the same system/vendor for both content and platform i18n. +It is possible, although very rare, to use the same system/vendor for both "dynamic" and "static" i18n. -For instance, one could imagine to store all its static content (platform i18n) within it's content i18n data. This design would have a few pros/cons: +For instance, one could imagine to store all its static content within it's dynamic i18n content. This design would have a few pros/cons: - Content is available online (CMS/back office) and may be updated by non-IT teams - Content needs to be fetched for each request (SSR), but that could be mitigated by using SSG -## A few words on "platform i18n" +## A few words on "static i18n" -I18n with Next.js isn't an easy topic, and our current implementation with platform content (Locize vendor) isn't optimal. +I18n with Next.js isn't an easy topic, and our current implementation with static content (Locize vendor) isn't optimal. -We believe the best way to deal with platform i18n (static content) is to use SSG. -Basically, the process is to fetch your i18n content at build time and generate your pages once and for all. +In short, we believe the best way to deal with static i18n is to use SSG. We currently use SSR, which is definitely sub-optimal and impacts performances and costs. + +### How to get it right + +Basically, the process could be to fetch your i18n content at build time and generate your pages once and for all. This avoids over-fetching your i18n provider for each end-user request, and also remove this vendor from the potential list of threats of your app. (even if your vendor API goes down, it won't affect your end-users because you only use its API at build time) -But it can be complicated to achieve depending on your limitations, and will be impacted by how many pages you have to build, for instance. +Such design also has various benefits and limitations. 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. + +It can be complicated to achieve depending on your needs and limitations, and will be impacted by how many pages you have to build, for instance. -## A few words on "content i18n" +## A few words on "dynamic i18n" -**Content i18n** is a bit more easier in our opinion. +**Dynamic i18n** is a bit more easier in our opinion. 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. diff --git a/docs/concepts/variants.md b/docs/concepts/variants.md index 4590e7c..cf8ae74 100644 --- a/docs/concepts/variants.md +++ b/docs/concepts/variants.md @@ -8,18 +8,14 @@ nav_order: 1 # Variants {: .no_toc } -## Table of contents -{: .no_toc .text-delta } - -- TOC -{:toc} +{% include page-toc.md %} --- ## What is a variant? -A variant is a variation of the boilerplate. Each variant provides different **built-in** features. - +- A variant is a "variation" of the boilerplate. It's the same as a "Preset" of features that are "ready-to-use", because they're built-in within that variant. +- Each variant provides different **built-in** features. - Each variant lives in the same NRN Github repository, but in a distinct **branch**. - Each variant has its own dedicated demo and "how to install" documentation. @@ -35,8 +31,8 @@ The boilerplate was built with re-usability in mind, but also tries to solve non - Analytics - Monitoring - API usage (consumption) -- Content i18n -- Platform i18n +- [Dynamic i18n](../reference/terminology#nrn-terms) (content) +- [Static i18n](../reference/terminology#nrn-terms) (website) >Those are non-trivial features, and they can't always be build using open source software. > @@ -45,7 +41,7 @@ The boilerplate was built with re-usability in mind, but also tries to solve non Variants are meant to cover as much possibilities as possible. For instance, you may want to use: - SSG or SSR - Multi-tenants or Multiple Single-Tenants or Single Tenant -- Platform i18n with Locize vendor, or implemented using static files (no vendor), or maybe you don't need this feature at all +- Static i18n with Locize vendor, or implemented using static files (no vendor), or maybe you don't need this feature at all - Sentry to monitor your app (client + server sides), but maybe you already use another different vendor and would like to stick with it - Analytics, but because you may use SSG only, and your needs are small then Google Analytics may be a better fit for you and avoid additional complexity - Etc. @@ -66,9 +62,9 @@ It's a waste of time if everybody has to do that on their own, and it strongly l Here is a short list of all variants that we consider to support in the future: - ST (as an alternative to current MST) - SSG (as an alternative to current SSR) -- Platform i18n without Locize provider (as an alternative to current Locize provider, which isn't free) -- No platform i18n and no content i18n support either - (completely remove platform/content i18n support as an alternative for those who don't need related i18n complexity and prefer to keep things simpler) +- Static i18n without Locize provider (as an alternative to current Locize provider, which isn't free) +- No static i18n and no dynamic i18n support + (completely remove any i18n support as an alternative for those who don't need related i18n complexity and prefer to keep things simpler) --- @@ -86,6 +82,26 @@ We do not plan on providing variants for: > > We are therefore open to add more/new tooling, but we must discuss it together first! :wink: +## How do I know which variant is best for me? + +A variant is nothing more than a preset of features that are built-in within. + +So, to decide which one you need, you must compare what features are available versus what features you actually need. +Also, some variants include non-free vendors, or vendors that only provide a limited plan. Depending on those things, you may chose one variant over another. + +Here is a summary of all features that are provided through variants: +- **Manage multiple B2B single-tenants**: Do you need to deploy different sites (one per customer) through the same code base (monorepo design)? If so, we've got you covered. +- **I18n**: Do you need to display your app in multiple languages? + If so, you should start with a variant that allows both ["dynamic i18n" and "static i18n"](../reference/terminology#nrn-terms). + - Also, depending on your needs, you may want to rely on a professional vendor to store, provide and help with i18n. + - For instance, our team love Locize for its [in-context editor](https://docs.locize.com/more/incontext-editor), because it really helps translators understand the context of a sentence, and our marketing/product team can make small changes without having to bother developers. +- **Connect with external APIs**: Do you need to use external APIs? It's very much likely for any app nowadays. + If so, you should start with a variant that provides built-in support. Make sure to select one that fits your needs, we only provide built-in support for GraphQL at the moment. +- **Monitoring**: Do you need to monitor what happens on your server and be warned about bugs and crashes? We bet you do. +- **Analytics**: Do you need to track usage of your features and know how many users visited your site this month? We bet you do. + +- **Tip**: Check out our [**Vendors overview**](../reference/vendors) + ---
@@ -93,7 +109,7 @@ We do not plan on providing variants for: [< Concepts](./){: .btn } - [Available variants](../getting-started/pick-variant){: .btn-blue } + [Find your variant](../getting-started/pick-variant){: .btn .btn-blue } [Environments and Stages >](./env-and-stages){: .btn .btn-purple } diff --git a/docs/contributing.md b/docs/contributing.md index 0e83cfc..7ccd657 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -7,13 +7,7 @@ nav_order: 90 # Contributing {: .no_toc } ---- - -## Table of contents -{: .no_toc .text-delta } - -- TOC -{:toc} +{% include page-toc.md %} --- diff --git a/docs/faq.md b/docs/faq.md index d711e98..dcb2c01 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -7,13 +7,7 @@ nav_order: 70 # FAQ {: .no_toc } ---- - -## Table of contents -{: .no_toc .text-delta } - -- TOC -{:toc} +{% include page-toc.md %} --- diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index 694286e..044321e 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -11,6 +11,7 @@ has_toc: false This section contains everything about how to get started with NRN. Here is the order we recommend: 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 +1. [Pre-requisites](./pre-requisites): Make sure all required tools are installed 1. [Quick start](./quick-start): Quickly get started with the most simple variant and run it on your own computer under 5mn 1. [Pick your variant](./pick-variant): **Advanced** - Find the variant that fits your needs through a comprehensive list of all possibilities _(make sure you are familiar with the basic [NRN concepts](../concepts) first!)_ diff --git a/docs/getting-started/pick-variant.md b/docs/getting-started/pick-variant.md index 26365fc..b453a8d 100644 --- a/docs/getting-started/pick-variant.md +++ b/docs/getting-started/pick-variant.md @@ -1,11 +1,11 @@ --- layout: default -title: Pick your variant +title: Find my variant parent: Getting started nav_order: 30 --- -# Find and pick your variant +# Find and use your variant {: .no_toc }
@@ -18,13 +18,13 @@ and help you get started to build your own project based on this variant. - Make sure you're up-to-date with the [terminology](../reference/terminology) being used.
+{% include page-toc.md %} + --- -## Table of contents -{: .no_toc .text-delta } +## How do I know which variant is best for me? -- TOC -{:toc} +[Check our guide](../concepts/variants#how-do-i-know-which-variant-is-best-for-me) --- @@ -33,10 +33,9 @@ and help you get started to build your own project based on this variant. You can get metadata at `/api/status` on any demo, because all variants provide this API (even those that aren't tagged with `ssr`) **Quick reminders**: +- The rendering mode (SSR/SSG) only affect how `pages` are served, it doesn't affect the API. - All `/api/*` endpoints are serverless functions, running under AWS Lambda -- Even when the build configuration doesn't use SSR, because Next.js allows a hybrid design, it stills allows some page to be served from a server - - All API endpoints are obviously always served by an actual server, they're not affected by SSG configuration, for instance. - - When pages don't use SSR, it only affects `/pages`, not the api endpoints themselves +- Next.js allows a hybrid design, thus allowing a per-page rendering mode (SSG or SSR) - The [database schema structure](../reference/demo-database-structure) is the same for all variants > We don't have examples using SSG at this time, but it is planned soon, don't hesitate to contribute! @@ -75,8 +74,8 @@ The plan is to release simpler variants soon. | SSR vs SSG | **SSR** | SSR by default for all pages (through `pages/_app`), SSG not available | | Tenancy | **MST** (Hybrid MT/ST) | Deploys 2 tenants on different domains (ST), sharing the same DB and API endpoint (MT) | | GraphQL API (GraphCMS) | :heavy_check_mark: | Advanced GraphCMS support | -| I18n content support (GraphCMS) | :heavy_check_mark: | Content from GraphCMS is localised | -| I18n platform support (Locize) | :heavy_check_mark: | Static content for the platform is localised using Locize (menu, links, etc.) | +| Dynamic i18n support (GraphCMS) | :heavy_check_mark: | Content from GraphCMS is localised (db records) | +| Static i18n support (Locize) | :heavy_check_mark: | Content for the platform is localised using Locize (menu, links, etc.) | | Monitoring (Sentry) | :heavy_check_mark: | Errors are sent to Sentry in real-time (both frontend and backend) | | Analytics (Amplitude) | :heavy_check_mark: | Fine-grained analytics is processed in real-time (1mn graph latency on free plans) | @@ -116,6 +115,14 @@ This will create a `nrn-variant-{{variant}}` folder in your current directory an {% include installation-guide-full.md variant=variant %} +#### Advanced configuration + +{% include installation-guide-tips.md %} + +#### Want to learn more? + +- Make sure to check our ["How to use" guides](../guides) for any of the vendor used above! + ---
diff --git a/docs/getting-started/pre-requisites.md b/docs/getting-started/pre-requisites.md new file mode 100644 index 0000000..0009d3c --- /dev/null +++ b/docs/getting-started/pre-requisites.md @@ -0,0 +1,31 @@ +--- +layout: default +title: Pre-requisites +parent: Getting started +nav_order: 15 +--- + +# Pre-requisites + +NRN expects the following to be already installed on your computer: + +- [NVM](https://github.com/nvm-sh/nvm) to manage installed Nodejs versions (allow to switch between versions) + - It's not really a requirement, but a good practice for any serious developer. + - If you don't use NVM, then please use node `v12` for the next steps. [Learn why](../guides/online-deployment/use-zeit) +- Node.js should be installed (it's installed by NVM, so you're probably already covered) +- [Git](https://git-scm.com/downloads) will be necessary to clone the repository on your computer. + +As you can see, there is no particular dependency to use NRN, all those tools are probably already installed on your computer! + +> NRN has only been extensively tested on **MacOS Catalina**, we expect **Unix-based OS** to behave properly, but **Windows** may behave differently (it shouldn't, but hasn't been tested). + +--- + +
+ + [< Video tutorials](./video-tutorials){: .btn } + + + [Quick start >](./quick-start){: .btn .btn-purple } + +
diff --git a/docs/getting-started/quick-start.md b/docs/getting-started/quick-start.md index ac09f7c..58dfde1 100644 --- a/docs/getting-started/quick-start.md +++ b/docs/getting-started/quick-start.md @@ -11,22 +11,22 @@ This short tutorial will explain how to perform a super quick local installation This tutorial uses the [**`v1-ssr`**](../getting-started/pick-variant) variant, which is the ~~simplest~~ _only one_ available at this time. -> It doesn't really matter if the selected variant fits your needs, the goal here is to give your a tour of what NRN can do for you, as quick as possible. +> It doesn't really matter if the selected variant fits your needs, the goal here is to give your a tour of what NRN can do for you, as quickly as possible. ## Step by step installation -> **Tip**: Using now@17+ is required for CI to work properly when deploying to Zeit, but we don't care about that as we just want to get started quickly. - {% include installation-guide-quick-start.md variant=v1-ssr %} +### Advanced configuration + {% include installation-guide-tips.md %} ---
-**Recommended**: +:books: **Recommended**: Go through the Concepts section: -Go through the Concepts section +Learn more about NRN concepts before getting your hands dirty :wink:
@@ -41,14 +41,14 @@ Go through the Concepts section ---
-**For experienced developers**: +:rocket: **For experimented developers** - _or if you're in a hurry_: -Pick the Variant that best fit your needs and get started ASAP +Pick the Variant that best fit your needs and it deploy online right now!
- [Pick your variant >](./pick-variant){: .btn .btn-blue } + [Find your variant >](./pick-variant){: .btn .btn-blue }
diff --git a/docs/getting-started/video-tutorials.md b/docs/getting-started/video-tutorials.md index dabcc24..8ae1192 100644 --- a/docs/getting-started/video-tutorials.md +++ b/docs/getting-started/video-tutorials.md @@ -33,6 +33,6 @@ Let's talk about the developer experience (DX) provided by NRN and how it helps [< Getting started](../){: .btn } - [Quick start >](./quick-start){: .btn .btn-purple } + [Pre-requisites >](./pre-requisites){: .btn .btn-purple }
diff --git a/docs/guides/analytics/use-amplitude.md b/docs/guides/analytics/use-amplitude.md index af0011a..8723fbf 100644 --- a/docs/guides/analytics/use-amplitude.md +++ b/docs/guides/analytics/use-amplitude.md @@ -11,17 +11,57 @@ nav_order: 20 Advices and "must-know" things regarding Amplitude usage. +{% include page-toc.md %} + --- -## Table of contents -{: .no_toc .text-delta } +## Overview + +### A few words about Amplitude vs Google Analytics + +When your want to perform Analytics in any app, people usually go for Google Analytics. **We don't.** + +GA is too limited, and huge, with tons of useless stuff. +We've used it, and we really don't recommend it for any SPA, especially when playing with universal app because it just sucks. + +> 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). +> It was designed and built for another world. **Not for SPA or CSR!** +> +> - _Our opinion_ + +Instead, we use (and recommend) Amplitude. +The world of analytics is huge, and isn't cheap. + +Amplitude allows to track events and users behaviour, who are two very different things, even if events are related to users. + +### A note about Amplitude's pricing + +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). + +Then, the cheapest plan is `Growth`, that **starts around $48k/year** (yup, it's a **huge** gap) -- TOC -{:toc} +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). +**They offer Scholarship for non-profit organisation too.** + +> 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. +> +> 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. + +Anyway, Amplitude is [one of the best out there for Analytics](https://stackshare.io/amplitude). + +If the free plan is enough for your needs, or if you can afford paid plans then don't hesitate. +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) + + +### Known limitations + +- Amplitude doesn't provide any backend-compatible API. + 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 businness needs. + See [https://github.com/amplitude/Amplitude-JavaScript/issues/164](https://github.com/amplitude/Amplitude-JavaScript/issues/164) --- -## Packages +## Dependencies > Amplitude is used to collect usage metrics (analytics) of the application. @@ -30,10 +70,9 @@ Amplitude **is used only on the frontend part of the application**. It is compos - [`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)) 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. -We only use react-amplitude to manipulate events. - -> **Known limitation**: Amplitude doesn't provide any backend-compatible API. See https://github.com/amplitude/Amplitude-JavaScript/issues/164 +We only use `react-amplitude` to manipulate events. +--- ## Chrome developer debug tool @@ -44,9 +83,11 @@ We only use react-amplitude to manipulate events. - [Tutorial](https://help.amplitude.com/hc/en-us/articles/360003032451-Instrumentation-Explorer-Debugger) - [Chrome plugin](https://chrome.google.com/webstore/detail/amplitude-instrumentation/acehfjhnmhbmgkedjmjlobpgdicnhkbp) +--- + ## Resources -- https://amplitude.com/ -- https://developers.amplitude.com/ -- https://amplitude.com/blog/category/inside-amplitude -- https://help.amplitude.com/hc/en-us +- [https://amplitude.com/](https://amplitude.com/) +- [https://developers.amplitude.com/](https://developers.amplitude.com/) +- [https://amplitude.com/blog/category/inside-amplitude](https://amplitude.com/blog/category/inside-amplitude) +- [https://help.amplitude.com/hc/en-us](https://help.amplitude.com/hc/en-us) diff --git a/docs/guides/graphql-api/setup-graphcms.md b/docs/guides/graphql-api/setup-graphcms.md index 5804bf9..da1bb06 100644 --- a/docs/guides/graphql-api/setup-graphcms.md +++ b/docs/guides/graphql-api/setup-graphcms.md @@ -11,13 +11,7 @@ nav_order: 10 Step by step guide about how to create and properly configure your GraphCMS account. ---- - -## Table of contents -{: .no_toc .text-delta } - -- TOC -{:toc} +{% include page-toc.md %} --- diff --git a/docs/guides/graphql-api/use-graphcms.md b/docs/guides/graphql-api/use-graphcms.md index 8f4daa7..58978a5 100644 --- a/docs/guides/graphql-api/use-graphcms.md +++ b/docs/guides/graphql-api/use-graphcms.md @@ -11,13 +11,7 @@ nav_order: 20 Advices and "must-know" things regarding GraphCMS usage. ---- - -## Table of contents -{: .no_toc .text-delta } - -- TOC -{:toc} +{% include page-toc.md %} --- @@ -87,7 +81,7 @@ We use it since September 2019 and haven't suffered any downtime since then, no --- -### Packages +### Dependencies We use multiple libraries to fetch data from GraphCMS. diff --git a/docs/guides/ide/index.md b/docs/guides/ide/index.md new file mode 100644 index 0000000..b22a28c --- /dev/null +++ b/docs/guides/ide/index.md @@ -0,0 +1,7 @@ +--- +layout: default +title: IDE +parent: Guides +nav_order: 1 +has_children: true +--- diff --git a/docs/guides/ide/setup-webstorm.md b/docs/guides/ide/setup-webstorm.md new file mode 100644 index 0000000..2cfb165 --- /dev/null +++ b/docs/guides/ide/setup-webstorm.md @@ -0,0 +1,17 @@ +--- +layout: default +title: How to setup WebStorm +parent: IDE +grand_parent: Guides +nav_order: 10 +--- + +# How to setup WebStorm IDE + +- Configure your IDE not to index `.next` and `.now` folders as they will eat a lot of your RAM because their files are changed very frequently! + - On WebStorm, right click on the folders and select `Mark directory as > Excluded`. + +- You can start the project in **debug mode** (built-in for WebStorm only) [by running the WebStorm "Debug" configuration in debug mode](https://youtu.be/3vbkiRAT4e8) + + +--- diff --git a/docs/guides/ide/use-webstorm.md b/docs/guides/ide/use-webstorm.md new file mode 100644 index 0000000..af9c874 --- /dev/null +++ b/docs/guides/ide/use-webstorm.md @@ -0,0 +1,32 @@ +--- +layout: default +title: How to use WebStorm +parent: IDE +grand_parent: Guides +nav_order: 10 +--- + +# How to use WebStorm IDE + +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. + +Therefore, we will provide **advanced WebStorm advices and configuration**. + +> This is a personal preference and **you can use any IDE** of your choosing with NRN. + +As of 2020, we recommend either + - [WebStorm](https://www.jetbrains.com/webstorm/) (paid, free for students) + - or [VSCode](https://code.visualstudio.com/) (free, OSS) + +> Please contribute if you wish to add advanced advices and configuration for other tools, such as VSCode. + +## Interactive debug mode + +In order to use step-by-step debugging (AKA "interactive debug"), there is a special configuration to apply to WebStorm IDE. + +You can start the project in **debug mode** [by running the WebStorm "Debug" configuration in debug mode](https://youtu.be/3vbkiRAT4e8) + +Beware that this will only allow for back-end debugging. +Frontend debug should be performed from the browser itself. + +--- diff --git a/docs/guides/online-deployment/use-zeit.md b/docs/guides/online-deployment/use-zeit.md index 3c175dd..8def31b 100644 --- a/docs/guides/online-deployment/use-zeit.md +++ b/docs/guides/online-deployment/use-zeit.md @@ -6,5 +6,22 @@ grand_parent: Guides nav_order: 20 --- -https://zeit.co/docs -https://zeit.co/blog +# How to use Zeit + +## Node.js runtime version + +Note that your code will be deployed on Zeit servers, which are running **AWS Lambda** on the background. + +- By default, Zeit will deploy using Node.js `v12.x` runtime, the `x` means it will automatically use the latest version. + - This means that you should update your `.nvmrc` to match the version that's actually being used by Zeit, 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". +- See [official Zeit Node.js supported versions](https://zeit.co/docs/runtimes#official-runtimes/node-js/node-js-version) +- 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. Zeit is just a proxy that simplifies things. +- We provide a built-in utility you can use on any online demo at `/api/status`, for instance at [https://nrn-v1-ssr-customer1.now.sh/api/status](https://nrn-v1-ssr-customer1.now.sh/api/status). + - You can also use this endpoint locally, or on your own deployments. + - **Tip**: As a security measure, you may want to either disable or protect that endpoint, using Basic-Auth for instance. + + +## Resources + +- https://zeit.co/docs +- https://zeit.co/blog diff --git a/docs/index.md b/docs/index.md index 3b6eda9..b47f2d6 100644 --- a/docs/index.md +++ b/docs/index.md @@ -99,7 +99,7 @@ Here is an overview of all the features covered by this boilerplate:
- _1: Note that your own code should support **universal rendering**, to re-use code as much as possible between frontend and backend (beware libraries you rely on, as they may not be universal)_ -- _2: I have reasonable doubts regarding how optimised the current implementation is (SEO, First Contentful Paint), and I'd love a community feedback on this!_ +- _2: We have reasonable doubts regarding how optimised the current implementation is (SEO, First Contentful Paint), and we'd love a community feedback on this!_
--- @@ -124,8 +124,6 @@ Here is an overview of all the features covered by this boilerplate: - Auto-add i18n keys with default translation when working locally - Strong **observability** of the system (monitoring) and push-notification on your own messaging channel (i.e: Slack) when things go wrong (thanks to [Sentry1](https://sentry.io/)) - Fine-grained frontend **analytics**, react-friendly, flexible, SPA-friendly (thanks to [Amplitude1**2**](https://amplitude.com/)) -- [_WIP - Contributions welcomed!_] [**Next Right Now Admin**](https://github.com/UnlyEd/next-right-now-admin), **a backoffice/admin site to manage your GraphQL API content**, based on [react-admin](https://github.com/marmelab/react-admin), forked from NRN itself! - _[V2](https://github.com/UnlyEd/next-right-now-admin/projects) aims at making it multi-tenants compliant_
- `advanced support`: Means that we took a very special care to support this, and that it's not as simple as one may believe diff --git a/docs/reference/demo-database-structure.md b/docs/reference/demo-database-structure.md index 48583b1..376e566 100644 --- a/docs/reference/demo-database-structure.md +++ b/docs/reference/demo-database-structure.md @@ -5,12 +5,20 @@ parent: Reference nav_order: 30 --- -### Demo database structure +# Demo database structure +{: .no_toc } + +{% include page-toc.md %} + +--- + +## GraphCMS vendor > Data structure of the GraphCMS database used as example. > -> This is only useful if you wish to understand the relationships and data structure of the demo, you don't really need it. -> But if you fork and try to rebuild the demo on your own GraphCMS endpoint, it'll come in handy. +> This is only useful if you wish to understand the relationships and data structure of the demo. +> +> It's only useful if try to rebuild the demo on your own GraphCMS endpoint (after cloning, for example). - customer - ref - Single line text, required, unique diff --git a/docs/reference/dependencies.md b/docs/reference/dependencies.md index 774cd05..e0b4c88 100644 --- a/docs/reference/dependencies.md +++ b/docs/reference/dependencies.md @@ -3,105 +3,34 @@ layout: default title: Dependencies parent: Reference nav_order: 60 ---- -Dependencies -=== - -> Documentation about the project's dependencies - - - -- [Dependencies](#dependencies) - * [Amplitude](#amplitude) - + [A note about Amplitude's pricing](#a-note-about-amplitudes-pricing) - * [Emotion](#emotion) - + [Note about `/** @jsx jsx */`](#note-about--jsx-jsx-) - * [FortAwesome/FontAwesome](#fortawesomefontawesome) - + [Note about FontAwesome usage](#note-about-fontawesome-usage) - * [Sentry](#sentry) - + [A note about Sentry usage](#a-note-about-sentry-usage) - * [Unly packages](#unly-packages) - * [Apollo with react](#apollo-with-react) - * [Bootstrap](#bootstrap) - + [Notes about Bootstrap/Reactstrap usage](#notes-about-bootstrapreactstrap-usage) - - [Notes about Reactstrap Tooltips and Modal (SSR-not-friendly)](#notes-about-reactstrap-tooltips-and-modal-ssr-not-friendly) - * [classnames](#classnames) - * [Cookies](#cookies) - + [Why not using `universal-cookie`?](#why-not-using-universal-cookie) - + [Cookies management abstraction `UniversalCookiesManager`](#cookies-management-abstraction-universalcookiesmanager) - * [css-to-react-native](#css-to-react-native) - * [deepmerge](#deepmerge) - * [GraphQL](#graphql) - * [I18n, i18next and Locize](#i18n-i18next-and-locize) - + [Language detection](#language-detection) - + [Translation](#translation) - * [isomorphic-unfetch](#isomorphic-unfetch) - * [json-stringify-safe](#json-stringify-safe) - * [Lodash](#lodash) - + [Note about Lodash TS typings](#note-about-lodash-ts-typings) - * [Next](#next) - * [rc-tooltip](#rc-tooltip) - * [React](#react) - * [recompose](#recompose) - * [webfontloader](#webfontloader) - * [winston](#winston) -- [Dev dependencies](#dev-dependencies) - * [@types](#types) - * [Now & Zeit](#now--zeit) - * [Debug WebStorm](#debug-webstorm) - * [Eslint](#eslint) - * [Tests](#tests) - + [Jest](#jest) - + [Cypress](#cypress) - * [Documentation](#documentation) - - - --- # Dependencies +{: .no_toc } -> Overview of the project deps, why we use them, and (not always) quick explanations about them +
+Overview of the project dependencies, **why** we use them, and **quick explanations** about them -All the packages listed here are under open source, non-restrictive license (MIT, ISC, etc.) +All the packages listed here are under **open source**, **non-restrictive license** (MIT, ISC, etc.) _The order follows the order in `package.json` (kinda alphabetical but not quite exactly `¯\_(ツ)_/¯`)_ +
-## Amplitude - -> A JavaScript SDK for tracking events and revenue to Amplitude. - -When your want to perform Analytics in any app, people usually go for Google Analytics. We don't. -GA is too limited, and huge, with tons of useless stuff. We've used it, and we really don't recommend it for any SPA, especially when playing with universal app because it just sucks. - -> 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). It was built for another world. Not for SPA! - -Instead, we use (and recommend) Amplitude instead. The world of analytics is huge, and isn't cheap. - -- [`amplitude-js`](https://www.npmjs.com/package/amplitude-js): Top-level amplitude official lib, used by react-amplitude. -- [`@amplitude/react-amplitude`](https://www.npmjs.com/package/react-amplitude): React-friendly amplitude lib, non-officially maintained. Really useful when working with react. +Only the common dependencies are listed here, not vendor-related dependencies. -Amplitude allows to track events and users behaviour, who are two very different things, even if events are related to users. +Vendor-related dependencies are listed per-vendor, in their respective ["How to use" guide](../guides). -### A note about Amplitude's pricing +{% include page-toc.md %} -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). - -Then, the cheapest plan is `Growth`, that **starts around $48k/year** (yup, it's a **huge** gap) - -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). -**They offer Scholarship for non-profit organisation too.** +--- -> 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. -> -> They told us then always find a way to provide Amplitude at an acceptable price for non-profit +## Dependencies -Anyway, Amplitude is [one of the best out there for Analytics](https://stackshare.io/amplitude), if the free plan is enough for your needs, or if you can afford paid plans. -Also, their react integration is really good, even though it's not officially maintained and could use some love. +Dependencies that are bundled to the end-user app. --- -## Emotion +### Emotion > Emotion is a library designed for writing css styles with JavaScript. [https://emotion.sh/docs/introduction](https://emotion.sh/docs/introduction) @@ -117,7 +46,7 @@ which allows to write components using either the `styled` notation, or the `css It's strongly recommended to read the official documentation about how to use it. -### Note about `/** @jsx jsx */` +#### Note about `/** @jsx jsx */` When using Emotion, the file must start with `/** @jsx jsx */` on top of it. - [Explanation](https://stackoverflow.com/questions/53803466/what-does-the-comment-jsx-jsx-do-in-the-emotion-css-in-js-library) @@ -127,17 +56,19 @@ When using Emotion, the file must start with `/** @jsx jsx */` on top of it. --- -## FortAwesome/FontAwesome +### FortAwesome/FontAwesome [FontAwesome](https://github.com/FortAwesome/Font-Awesome) is an awesome icon toolkit. We use the pro (paid) version, but a free version is also available. - [`@fortawesome/fontawesome-svg-core`](https://www.npmjs.com/package/@fortawesome/fontawesome-svg-core): Necessary to use font-awesome with a node project. Contains libs to config the FA library. (see `src/pages/_app.tsx`) -- [`@fortawesome/pro-light-svg-icons`](https://www.npmjs.com/package/@fortawesome/pro-light-svg-icons): Contains the icons themselves, there is one package per free/pro and kind of icon (light, regular, solid), and specific packages per technology stack (vue, angular, react-native, etc.) +- [`@fortawesome/free-light-svg-icons`](https://www.npmjs.com/package/@fortawesome/fontawesome-free): Contains the icons themselves, there is one package per free/pro and kind of icon (light, regular, solid), and specific packages per technology stack (vue, angular, react-native, etc.) - [`@fortawesome/react-fontawesome`](https://www.npmjs.com/package/@fortawesome/react-fontawesome): Contains the icons themselves -### Note about FontAwesome usage +[Installation tutorial](https://fontawesome.com/how-to-use/on-the-web/setup/using-package-managers) + +#### Note about FontAwesome usage FontAwesome is a little trickier to use that we would like to. @@ -163,7 +94,7 @@ import { FontAwesomeIcon } from '@fortawesome/react-fontawesome'; --- -## Sentry +### Sentry > Sentry provides open-source and hosted error monitoring that helps all software teams discover, triage, and prioritize errors in real-time. @@ -177,7 +108,7 @@ Those errors are also sent to our Slack channel `sentry-monitoring`. Sentry provides 2 different packages, with different abilities (but a very similar API) for browser and server usage. -### A note about Sentry usage +#### A note about Sentry usage In the source code, we always use `@sentry/node`, which is automatically converted at build step by babel. (see [next.config.js](next.config.js)) @@ -185,23 +116,23 @@ This way, we always use the same import, which is linked to the right package ba --- -## Unly packages +### Unly packages We use some of our own packages. They are all hosted on ou [GitHub repository](https://github.com/UnlyEd), and all under MIT license. - [`@unly/utils`](https://github.com/UnlyEd/utils): This is a utility library which contains various helpers. This repository was created because those helpers are used amongst several projects and were copy/pasted, which is a bad practice. - [`@unly/utils-simple-logger`](https://github.com/UnlyEd/utils-simple-logger): Logger based on [Winston](https://github.com/winstonjs/winston) with sane default so that it only logs `error` in production and filter other logs, while keeping them all in non-production environments. - Basically avoids to increase cost by logging useless logs in production. + Basically avoids to increase cost by logging useless logs in production. - [`@unly/universal-language-detector`](https://github.com/UnlyEd/universal-language-detector): Language detector that works universally (browser + server) - Meant to be used with a universal framework, such as Next.js --- -## [Apollo with react](https://github.com/apollographql/react-apollo) +### [Apollo with react](https://github.com/apollographql/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. - [`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. - Even though it may seems unused, this package is required as peer-dependency. + Even though it may seems unused, this package is required as peer-dependency. - [`apollo-cache-inmemory`](https://www.npmjs.com/package/apollo-cache-inmemory): apollo-cache-inmemory is the 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. - [`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. - [`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. @@ -219,7 +150,7 @@ Our implementation is based on [this example](https://github.com/tomanagle/Graph --- -## [Bootstrap](https://getbootstrap.com/) & [Reactstrap](https://reactstrap.github.io/) +### [Bootstrap](https://getbootstrap.com/) & [Reactstrap](https://reactstrap.github.io/) > We use Reactstrap as a Components library, which is itself based on Bootstrap. @@ -227,7 +158,7 @@ Our implementation is based on [this example](https://github.com/tomanagle/Graph - [`reactstrap`](https://www.npmjs.com/package/reactstrap): - [`@zeit/next-css`](https://github.com/zeit/next-plugins/tree/master/packages/next-css): [Additional Next configuration](https://stackoverflow.com/a/50002905/2391795) necessary to gain the ability to `import` `.css` files. -### Notes about Bootstrap/Reactstrap usage +#### Notes about Bootstrap/Reactstrap usage > We are not quite satisfied with Reactstrap, to be honest. But we haven't found a better alternative so far (mostly because we're used to bootstrap, and lack of time for R&D). > @@ -248,7 +179,7 @@ We strongly suggest using another lib for Tooltips such as `rc-tooltip`. --- -## classnames +### classnames > `classnames` is just the must-have tool to use to manipulate dynamic className property @@ -256,19 +187,19 @@ We strongly suggest using another lib for Tooltips such as `rc-tooltip`. --- -## Cookies +### Cookies > It's hard (or at least, non-trivial) to make cookies work universally with Next.js - [`js-cookie`](https://github.com/js-cookie/js-cookie): Used to **WRITE** cookies from the **client** side. A simple, lightweight JavaScript API for handling browser cookies - [`cookies`](https://www.npmjs.com/package/cookies): Used to **WRITE** cookies from the **server** side. Cookies is a node.js module for getting and setting HTTP(S) cookies. Cookies can be signed to prevent tampering, using Keygrip. It can be used with the built-in node.js HTTP library, or as Connect/Express middleware. - I'm not sure if that lib is the best choice, but it did work back then. Other alternative may be https://github.com/maticzav/nookies + I'm not sure if that lib is the best choice, but it did work back then. Other alternative may be https://github.com/maticzav/nookies - [`next-cookies`](https://www.npmjs.com/package/next-cookies): Used to **READ** cookies universally (cannot write). Tiny little function for getting cookies on both client & server with next.js. - This enables easy client-side and server-side rendering of pages that depend on cookies. + This enables easy client-side and server-side rendering of pages that depend on cookies. A `cookies` prop is available to all **Page** and **Layout** components (through the `_app.tsx:render()`). -### Why not using `universal-cookie`? +#### Why not using `universal-cookie`? [`universal-cookie`](https://github.com/reactivestack/cookies/tree/master/packages/universal-cookie) looks promising and if you know about it, you may ask yourself why we don't use it instead of one package for the client side, and another one for the server side. @@ -276,7 +207,7 @@ you may ask yourself why we don't use it instead of one package for the client s Well, the answer is straightforward: **It does not work**. See [https://github.com/reactivestack/cookies/issues/256](https://github.com/reactivestack/cookies/issues/256) -### Cookies management abstraction `UniversalCookiesManager` +#### Cookies management abstraction `UniversalCookiesManager` We've built our own `UniversalCookiesManager` utility class to deal with cookies in a universal way (same API on client/server sides). @@ -284,7 +215,7 @@ It basically hides away the complexity, and allows for source code reusability. --- -## css-to-react-native +### css-to-react-native > Converts CSS text to a React Native stylesheet object. > @@ -300,7 +231,7 @@ Currently used by [GraphCMSAsset.tsx](src/components/GraphCMSAsset.tsx) --- -## deepmerge +### deepmerge > Merges the enumerable properties of two or more objects deeply. @@ -311,14 +242,14 @@ Handles deeply nested objects. --- -## GraphQL +### GraphQL - [`graphql`](https://www.npmjs.com/package/graphql): Client for connecting to a GraphQL endpoint. - [`graphql-tag`](https://www.npmjs.com/package/graphql-tag): Helpful utilities for parsing GraphQL queries. - Useful to write plain-text GraphQL query using the `gql` tag, that can be validated by other tools, such as **JS GraphQL IntelliJ Plugin**. + Useful to write plain-text GraphQL query using the `gql` tag, that can be validated by other tools, such as **JS GraphQL IntelliJ Plugin**. - [JS GraphQL IntelliJ Plugin](https://github.com/jimkyndemeyer/js-graphql-intellij-plugin): GraphQL language support for WebStorm, IntelliJ IDEA and other IDEs based on the IntelliJ Platform. - The plugin is available using WebStorm directly. To install it, open your IDE "Settings", "Plugins", "Marketplace" and search for "GraphQL". - But, it should be automatically made available by default. (through shared IDE config) + The plugin is available using WebStorm directly. To install it, open your IDE "Settings", "Plugins", "Marketplace" and search for "GraphQL". + But, it should be automatically made available by default. (through shared IDE config) The usage of both `gql` and the IntelliJ GraphQL plugin is awesome, it allows to write GraphQL queries (see [gql folder](./src/gql)) and have auto-completion and validation from WebStorm itself. @@ -326,27 +257,27 @@ To refresh the GraphQL spec, just run the `.graphqlconfig` file by opening it an --- -## I18n, i18next and Locize +### I18n, i18next and Locize -### Language detection +#### Language detection We rely on a few packages for I18n: - [`accept-language-parser`](https://www.npmjs.com/package/accept-language-parser): Parses the accept-language header from an HTTP request and produces an array of language objects sorted by quality. Together, those packages are used in [i18n.ts](src/utils/i18n.ts) and are used to resolve the languages/codes used/preferred by the end user. We do it manually instead of relying on another lib that would detect the language for us, because we need to be consistent with the language displayed to the end user, and need to provide the exact same value to GraphCMS and Locize. -### Translation +#### Translation We also rely on those packages to manage the translations: - [`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. - It will allow you to save missing keys containing both default value and context information - **This backend is used when using the browser.** + It will allow you to save missing keys containing both default value and context information + **This backend is used when using the browser.** - [`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. - **This backend is used when using node (server).** + **This backend is used when using node (server).** - [`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. - Enabling the editor by querystring ?locize=true you can click any text content on your website to open it on the right side editor window - **This plugin is used when using the browser.** + Enabling the editor by querystring ?locize=true you can click any text content on your website to open it on the right side editor window + **This plugin is used when using the browser.** - [`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. - **This plugin is used when using node (server).** + **This plugin is used when using node (server).** It was quite complicated to configure Next with Locize, mostly because of the universal way Next works, while Locize has dedicated packages depending on the runtime engine. @@ -355,7 +286,7 @@ It was quite complicated to configure Next with Locize, mostly because of the un --- -## isomorphic-unfetch +### isomorphic-unfetch > Can be used to either polyfill the whole app, or used as a `fetch` function. _(Stands for "isomorphic universal fetch")_ @@ -367,7 +298,7 @@ The main reason for choosing this one is its very small bundle size, and it's un --- -## json-stringify-safe +### json-stringify-safe > Used to safely stringify JSON objects. Works even when they have circular dependencies @@ -377,7 +308,7 @@ Use at your convenience. We weren't sure whether to use `json-stringify-safe` or --- -## [Lodash](https://lodash.com/docs/4.17.15) +### [Lodash](https://lodash.com/docs/4.17.15) > A modern JavaScript utility library delivering modularity, performance & extras. @@ -392,7 +323,7 @@ We're not sure if it's better/easier/wiser. We suppose it should decrease the bu We use plenty of utilities from lodash. Make sure read their [documentation](https://lodash.com/docs/). -### Note about Lodash TS typings +#### Note about Lodash TS typings We also load each TS types one-by-one. One advantage of that is that **we can decide not to load typings that do not work**. @@ -403,19 +334,19 @@ We also load each TS types one-by-one. One advantage of that is that **we can de --- -## Next +### Next > Next.js framework package and plugins/utilities. - [`next`](https://www.npmjs.com/package/next): Next.js framework package. - See [tutorial](https://nextjs.org/learn/basics/getting-started). + See [tutorial](https://nextjs.org/learn/basics/getting-started). - [`next-cookies`](https://www.npmjs.com/package/next-cookies): See [Cookies](#cookies) - [`next-with-apollo`](https://www.npmjs.com/package/next-with-apollo): Apollo HOC for Next.js --- -## rc-tooltip +### rc-tooltip > React Tooltip component @@ -425,7 +356,7 @@ Marked as alpha-3 version but stable. **Much better than Reactstrap Tooltip comp --- -## React +### React > React package and plugins/utilities. @@ -439,7 +370,7 @@ Marked as alpha-3 version but stable. **Much better than Reactstrap Tooltip comp --- -## recompose +### recompose > Used to compose multiple HOC together @@ -447,7 +378,7 @@ Marked as alpha-3 version but stable. **Much better than Reactstrap Tooltip comp --- -## webfontloader +### webfontloader > Web Font Loader gives you added control when using linked fonts via @font-face. > @@ -460,7 +391,7 @@ Marked as alpha-3 version but stable. **Much better than Reactstrap Tooltip comp --- -## winston +### winston > Peer-dependency of `@unly/utils-simple-logger` @@ -471,7 +402,9 @@ Marked as alpha-3 version but stable. **Much better than Reactstrap Tooltip comp # Dev dependencies -## @types +Development dependencies that are required to run the program locally (the bundle won't contains these dependencies). + +### @types > TypeScript requires Typings to resolve types. > @@ -493,18 +426,18 @@ Marked as alpha-3 version but stable. **Much better than Reactstrap Tooltip comp > > They are meant to make the development process easier/faster. -## Now & Zeit +### Now & Zeit > Official packages from Zeit/Now, the company hosting our application - [`@now/node`](https://zeit.co/docs/runtimes#official-runtimes/node-js): Used as a dev dependency, it's useful to provide [TypeScript support](https://zeit.co/docs/v2/serverless-functions/supported-languages/#node.js-typescript-support:). - Such as for `import { NowRequest, NowResponse } from '@now/node'`. + Such as for `import { NowRequest, NowResponse } from '@now/node'`. - [`now`](https://www.npmjs.com/package/now): The Now CLI [https://github.com/zeit/now](https://github.com/zeit/now) [https://www.npmjs.com/package/now](https://www.npmjs.com/package/now) - [`@zeit/next-css`](https://github.com/zeit/next-plugins/tree/master/packages/next-css): [Additional Next configuration](https://stackoverflow.com/a/50002905/2391795) necessary to gain the ability to `import` `.css` files. - Used to import other libs such as `bootstrap.css`. + Used to import other libs such as `bootstrap.css`. - [`@zeit/next-source-maps`](https://www.npmjs.com/package/@zeit/next-source-maps): Generate source maps during production build in your Next.js project -## Debug WebStorm +### Debug WebStorm > Packages meant to help with the debug of the application @@ -517,7 +450,7 @@ Running the Debug configuration in `debug` mode allows to pause execution and us --- -## Eslint +### Eslint > Eslint helps us enforce code style and check for typos and errors during the development process @@ -535,22 +468,22 @@ Run `yarn lint` to run the linter. --- -## Tests +### Tests -### [Jest](https://jestjs.io/) +#### [Jest](https://jestjs.io/) > Jest is our test runner, it runs our tests to make sure we don't ship regressions to our end users - [`jest`](https://www.npmjs.com/package/jest): Jest is a delightful JavaScript Testing Framework with a focus on simplicity. - [`jest-extended`](https://www.npmjs.com/package/jest-extended): Additional Jest matchers. Provides additional built-in tests for ease of testing. - [`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. - 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. + 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. - [`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. **Known issues**: - `jest-emotion`: [Breaks tests](https://github.com/emotion-js/emotion/issues/1440#issuecomment-551235747) -### Cypress +#### Cypress > Cypress is a tool that helps performing end-to-end (E2E) tests that aim at testing the UI and the user workflows. > @@ -574,10 +507,10 @@ It's a bit harder to setup, here is a [tutorial](https://www.cypress.io/blog/201 --- -## Documentation +### Documentation - [`markdown-toc`](https://www.npmjs.com/package/markdown-toc): Generate a markdown TOC (table of contents). - _Uses many dependencies, many of them outdated (handlebars) and containing security issues, but we don't care much about those as they aren't shipped in the build, but only present on the developer's local machine._ + _Uses many dependencies, many of them outdated (handlebars) and containing security issues, but we don't care much about those as they aren't shipped in the build, but only present on the developer's local machine._ - [`version-bump-prompt`](https://www.npmjs.com/package/version-bump-prompt): Used to make it easier to bump versions. diff --git a/docs/reference/folder-structure.md b/docs/reference/folder-structure.md index eeaeb36..dc29e7b 100644 --- a/docs/reference/folder-structure.md +++ b/docs/reference/folder-structure.md @@ -4,9 +4,14 @@ title: Folder structure parent: Reference nav_order: 20 --- + # Project folders structure -> Overview of the project folder and files structure +
+Overview of the project folder and files structure +
+ +--- - `cypress`: Folder used by Cypress (E2E), see ["Getting started"](https://docs.cypress.io/guides/getting-started/installing-cypress.html#npm-install) - `public`: Static files, see ["Static file serving](https://nextjs.org/docs/basic-features/static-file-serving) diff --git a/docs/reference/terminology.md b/docs/reference/terminology.md index eb44472..59f09a4 100644 --- a/docs/reference/terminology.md +++ b/docs/reference/terminology.md @@ -6,10 +6,48 @@ nav_order: 10 --- # Terminology +{: .no_toc } + +
+Definition of terms used in NRN documentation and source code. +
+ +{% include page-toc.md %} + +--- + +## Common terms + +##### SSR +[Server Side Rendering](https://nextjs.org/features/server-side-rendering#benefits) + +##### SSG +[Static Site Generation](https://nextjs.org/blog/next-9-3#next-gen-static-site-generation-ssg-support) + +##### ST +[Single-Tenant](https://www.liquidweb.com/kb/what-is-single-tenant-vs-multi-tenant-software/) - Single-tenancy is an architecture in which a single instance of a software application and supporting infrastructure serves one customer (i.e., tenant). + +##### MT +[Multi-Tenants](https://www.liquidweb.com/kb/what-is-single-tenant-vs-multi-tenant-software/) - Multi-tenancy is an architecture in which a single instance of a software application serves multiple customers (tenants). + +##### MST +[Multiple Single-Tenants](https://www.pega.com/insights/articles/cloud-hybrid-tenancy-replacing-single-and-multi-tenancy) - Hybrid-tenancy is where microservice architectures leverage services that are both single- and multi-tenant to optimize the balance of performance, scale, and security. + +##### TTM +[Time to market](https://en.wikipedia.org/wiki/Time_to_market) + +--- + +## NRN terms + +Those terms are specific to NRN and you're not likely to find a definition elsewhere. + +##### [Variant](../concepts/variants) +Similar to a preset of features that are built-in within. Helps to quickly get started a new project. + +##### Dynamic i18n +Content-related (i.e: Post title in FR + EN). + +##### Static i18n +Everything that isn't related to dynamic content (i.e: Site links, any content that is static and not related to dynamic data). -- SSR: [Server Side Rendering](https://nextjs.org/features/server-side-rendering#benefits) -- SSG: [Static Site Generation](https://nextjs.org/blog/next-9-3#next-gen-static-site-generation-ssg-support) -- ST: [Single-Tenant](https://www.liquidweb.com/kb/what-is-single-tenant-vs-multi-tenant-software/) - Single-tenancy is an architecture in which a single instance of a software application and supporting infrastructure serves one customer (i.e., tenant). -- MT: [Multi-Tenants](https://www.liquidweb.com/kb/what-is-single-tenant-vs-multi-tenant-software/) - Multi-tenancy is an architecture in which a single instance of a software application serves multiple customers (tenants). -- MST: [Multiple Single-Tenants](https://www.pega.com/insights/articles/cloud-hybrid-tenancy-replacing-single-and-multi-tenancy) - Hybrid-tenancy is where microservice architectures leverage services that are both single- and multi-tenant to optimize the balance of performance, scale, and security. -- TTM: [Time to market](https://en.wikipedia.org/wiki/Time_to_market) diff --git a/docs/reference/vendors.md b/docs/reference/vendors.md index 433619e..df05e77 100644 --- a/docs/reference/vendors.md +++ b/docs/reference/vendors.md @@ -12,8 +12,9 @@ nav_order: 19 Comprehensive overview of all vendors available with focus on what to be aware of.
-- TOC -{:toc} +{% include page-toc.md %} + +--- ## Key figures diff --git a/docs/reference/videos.md b/docs/reference/videos.md index a4465b7..001ea5e 100644 --- a/docs/reference/videos.md +++ b/docs/reference/videos.md @@ -6,12 +6,18 @@ nav_order: 50 --- # Videos +{: .no_toc } + +{% include page-toc.md %} + +--- ## Introduction videos - [Part 1 - Overview of Next Right Now (15 minutes)](http://youtu.be/kltkFwnFL-k?hd=1): This video features Zeit deployments, i18n, GraphCMS, Locize in-context editor, Sentry monitoring, Amplitude analytics, CI/CD Github Actions - [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 +--- ## Advanced guides diff --git a/src/pages/_app.tsx b/src/pages/_app.tsx index 64d474a..e21fd39 100644 --- a/src/pages/_app.tsx +++ b/src/pages/_app.tsx @@ -179,7 +179,7 @@ class NRNApp extends NextApp { i18nextInstance, }; - // XXX For an unknown reason, I noticed 2 render() calls. (each render call starts a new graphql request, and it makes debugging harder) + // XXX For an unknown reason, we noticed 2 render() calls. (each render call starts a new graphql request, and it makes debugging harder) // The first one doesn't contain any data from the server (no data, almost nothing) and therefore result in errors along the react sub tree // The second contains the expected data // Due to this behaviour, an "isSSRReadyToRender" variable has been introduced, to make sure we only render the components when all the data have been provided diff --git a/src/utils/i18nextLocize.ts b/src/utils/i18nextLocize.ts index 4a8d2a6..739d977 100644 --- a/src/utils/i18nextLocize.ts +++ b/src/utils/i18nextLocize.ts @@ -185,7 +185,7 @@ export const locizeBackendOptions = { * Instead, we manually fetch (pre-fetch) the translations ourselves from the _app:getInitialProps, so that they're available both on the client and the server * @see https://github.com/i18next/i18next/issues/1373 * - * XXX Make sure you don't use "auto" publish format, but either "nested" or "flat", to avoid the format to dynamically change (I personally recommend "nested") + * XXX Make sure you don't use "auto" publish format, but either "nested" or "flat", to avoid the format to dynamically change (We recommend "nested") * @see https://faq.locize.com/#/general-questions/why-is-my-namespace-suddenly-a-flat-json * * XXX Caching is quite complicated, because the caching strategy depends on the runtime engine (browser vs server) and the stage (development, staging, production)