Merge remote-tracking branch 'origin/main' into feature/error-boundaries

.eslintrc.json

@@ -1,9 +1,26 @@
 {
-  "extends": ["next/core-web-vitals", "plugin:storybook/recommended", "plugin:prettier/recommended", "prettier"],
+  "extends": [
+    "plugin:tailwindcss/recommended",
+    "next/core-web-vitals",
+    "plugin:storybook/recommended",
+    "plugin:prettier/recommended",
+    "prettier"
+  ],
   "plugins": ["@typescript-eslint"],
   "rules": {
     "prettier/prettier": "error",
     "@typescript-eslint/no-unused-vars": "error"
   },
+  "overrides": [
+    {
+      "files": ["*.ts", "*.tsx", "*.js"],
+      "parser": "@typescript-eslint/parser"
+    }
+  ],
+  "settings": {
+    "tailwindcss": {
+      "callees": ["cn"]
+    }
+  },
   "ignorePatterns": ["storybook-static/**"]
 }

.github/workflows/chromatic.yml

@@ -6,9 +6,15 @@ jobs:
   chromatic-deployment:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v1
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '>=20.18.0'
       - name: Install dependencies
-        run: yarn
+        run: yarn install --frozen-lockfile
       - name: Publish to Chromatic
         uses: chromaui/action@v1
         with:

.gitignore

@@ -12,6 +12,10 @@
 /.next/
 /out/
 
+# storybook
+/storybook-static
+/build-storybook.log
+
 # production
 /build
 

.husky/commit-msg

@@ -0,0 +1 @@
+npx --no-install commitlint --edit "$1"

.nvmrc

@@ -0,0 +1 @@
+v20.18.0

.prettierignore

@@ -0,0 +1,3 @@
+# Ignore gql
+gql/*
+

.prettierrc.json

@@ -22,9 +22,11 @@
   "printWidth": 120,
   "semi": true,
   "singleQuote": true,
-  "tailwindFunctions": ["cn"],
   "trailingComma": "es5",
   "tabWidth": 2,
   "useTabs": false,
-  "plugins": ["@ianvs/prettier-plugin-sort-imports", "prettier-plugin-curly", "prettier-plugin-tailwindcss"]
+  "plugins": [
+    "@ianvs/prettier-plugin-sort-imports",
+    "prettier-plugin-curly"
+  ]
 }

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 JAKALA
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,90 +1,94 @@
-# Next Contentful Starterkit
+# Next.js Contentful Starterkit
 
-This starterkit is meant to provide a good mix of best practices for working with Contentful in NextJS. It doesn't pretend to be the only way, but it is meant to address the main painpoints concerning data-fetching, component resolution, live previews, configuration management and App development. We believe a good starterkit is use-case based, but there is no good way to model all use-cases in same starter, so our use-case is a marketing or corporate site, it fact, it is modeled around Contentful's own [Marketing Template](https://www.contentful.com/starter-templates/marketing-website/) content model.
+This starterkit is meant to provide a good mix of best practices for working with Contentful in Next.js. It doesn't pretend to be the only way, but it is meant to address the main painpoints concerning data-fetching, component resolution, live previews, configuration management and App development. We believe a good starterkit is use-case based, but there is no good way to model all use-cases in same starter, so while we're starting as a marketing site, it may evolve later. In fact, it is modeled around Contentful's own [Marketing Template](https://www.contentful.com/starter-templates/marketing-website/) content model, with a slight twist on the content part.
 
-The starterkit's cornerstone is our data-fetching solution and it's typesafety. The goal is to have best-in-class Typescript-enabled, graphql-powered data fetching to eliminate guessing games in our components and provide full type definitions for free. The full list of current features with descriptions can be found below.
+The starterkit's cornerstone is our data-fetching solution and it's typesafety. The goal is to have best-in-class Typescript-enabled, graphql-powered data fetching to eliminate guessing games in our components and provide full type definitions for free. The list of current features with descriptions can be found below.
 
 ## Features
 
-- **NextJS App Router** usage for modern **React Server Components** approach - we think this is the way the industry will move and it is a huge benefit for traditional websites to do data fetching only on the server and keep client-bundle lean
-- **GraphQL** + **GraphQL Codegen** with **client-preset** plugin + Typescript for data fetching - we believe the best way to benefit from a GraphQL backend on the frontend is to use Typescript and be informed of what is available to you when you do data fetching, and GraphQL Codegen ensures you are not “lying to yourself” in your types by generating them from the API.
+- **Next.js App Router** usage for modern **React Server Components** approach - we think this is the way the industry will move to and it is a huge benefit for traditional websites to do data fetching only on the server and keep client bundle lean
+- **GraphQL** + **gql.tada** plugin + Typescript for data fetching - we believe the best way to benefit from a GraphQL backend on the frontend is to use Typescript and be informed of what is available to you when you do data fetching, and gql.tada ensures you are not “lying to yourself” in your types by inferring them from the API.
 - **Cypress testing** - we include a configured Cypress.io testing suite with ability to do both Component and E2E testing using Cucumber/BDD style syntax (optionally you can use traditional spec files too)
+- **Reference Component Architecture** - we use Tailwind and shadcn/ui for the UI layer as a base, but more importantly the starter ships with reference component architecture that promotes UI component best practices. We focus on ability to reuse UI across projects, use of React Server Components for data-fetching and we demostrate how Contentful data can be integrated with a UI design system while preserving all Next.js features and Contentful features as part of the integration.
 - **Component Renderer** - example of how to take a full tree of components and render them using a mapping of contentTypes to React components
 - **Draft Mode** - preview mode for your application for Contentful Preview API usage
-- Use of **Contentful Live Preview** - contentful live previews let you edit components side by side with a visual representation and Live Preview SDK also lets you annotate specific fields you are editing to get to the editor screen by just clicking “Edit” button on the frontend. We also integrated live updates, which will show result of content changes immediately as opposed to waiting for content to auto-save in Contentful
+- **Contentful Live Preview** - Contentful live previews let you edit components side by side with a visual representation and Live Preview SDK also lets you annotate specific fields you are editing to get to the editor screen by just clicking “Edit” button on the frontend. We also integrated live updates, which will show result of content changes immediately as opposed to waiting for content to auto-save in Contentful.
+- **Contentful Content Source Maps** - Optionally use Contentful Content Source Maps feature to get Live Preview SDK annotations without manually annotating your components, as well as get Vercel Content Link for Vercel customers.
 
 ## Getting Started
 
-Clone the repo of course ;)
+1. This project is a template, feel free to either clone it (to preserve project history) or use click "Use this template" to create a repository with a single init commit.
+   As soon as you have a repository, clone it locally
+2. Install dependencies with:
 
-### Contentful access
+```
+yarn install
+```
 
-To develop locally, you will want to connect to a Contentful instance that has the same data model as we use to develop, there are 2 ways to do that:
+3. Setup Contenful access
+   To develop locally, you will want to connect to a Contentful instance that has the same data model as we use to develop, there are 3 ways to do that:
 
-1. You could get access to an existing space that follows Contentful Marketing Template content model, for example a collegue could share his space with you
-2. You could create your own space with https://www.contentful.com/starter-templates/marketing-website/. Keep in mind, new templates today can only be deployed on brand new Contentful accounts, so you might have to create a new account with a new email to do that, but this shouldn't be a problem, as it's free.
+- You could get access to an existing space that follows Contentful Marketing Template content model, for example a colleague could share his space with you
+- You could create your own space with https://www.contentful.com/starter-templates/marketing-website/. Keep in mind, new templates today can only be deployed on brand new Contentful accounts, so you might have to create a new account with a new email to do that, but this shouldn't be a problem, as it's free.
+- You can start from scratch and use the contentful CLI and `/migrations/ctf-seed.json` to [import](https://www.contentful.com/developers/docs/tutorials/cli/import-and-export/) our demo content into your own contentful instance: `yarn seed --environment-id=[ENVIRONMENT_ID] --space-id=[SPACE_ID]`
 
-### Configure environment
+You will want to get a CDA and CPA API keys by using this [guide](https://www.contentful.com/developers/docs/references/authentication/#api-keys-in-the-contentful-web-app)
+
+4. Configure environment
 
 Create .env.local in root directory of the repo with the following contents:
 
 ```
 CONTENTFUL_SPACE=<space id>
 CONTENTFUL_DELIVERY_API=<delivery api key>
-CONTENTFUL_PREVIEW_API=<preview api key>****
+CONTENTFUL_PREVIEW_API=<preview api key>
 CONTENTFUL_ENVIRONMENT=master
 CONTENTFUL_PREVIEW_SECRET=secret
+# Enable or disable Content Source Maps, see https://www.contentful.com/developers/docs/tools/vercel/content-source-maps-with-vercel/
+CONTENTFUL_USE_CONTENT_SOURCE_MAPS=true
 ```
 
-### Dev Server
+5. Run Dev Server
 
 ```bash
 yarn dev
 ```
 
 Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
 
-### GraphQL Docs
-
-#### Regenerate graphql schema
-
-If you're adding new content types or making changes to the content model, you will need to generate a new graphql schema to get type inference in Typescript working and to get autocomplete in IDE. This can be done by running:
-
-```bash
-yarn generate:schema
-```
+## Documentation
 
-After new types are generated, you will get changes in `./gql/` folder that you'll have to commit after you are done developing the feature.
-Keep in mind, schema generation will take your `.env.local` and read the CONTENTFUL_ENVIRONMENT you are pointing to, so if you create a new content type on a different environment, it will not be pulled, or the opposite, if you have unwanted content types in your sandbox environment, they will all appear in the schema. Make sure you commit changes you intend to commit!
+- [Component Architecture](./docs/components.md)
+- [Components UI Folder](./components/ui/README.md)
+- [Data-fetching guide](./docs/data-fetching.md)
+- [Features guide](./docs/features.md)
+- [Analytics guide](./components/analytics/README.md)
+- [Architecture Decision Records](./docs/decisions/)
+- [Next.js docs](https://nextjs.org/docs)
 
-### Configure editor to use gql.tada
+## Deploy to Vercel
 
-In order for gql.tada's GraphQLSP plugin to work (and infer types), you need to have local Typescript server making the type inference (`node_modules/typescript/lib`)
+The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
 
-If you are using VSCode, the .vscode/settings.json in the repo is already configured to use the local Typescript server.
+Check out our [Next.js deployment documentation](https://nextjs.org/docs/deployment) for more details.
 
-If using Webstorm, make sure you configure the Typescript interpretter from node_modules/typescript/lib as well under Settings -> Language & Frameworks -> Typescript
+## Support
 
-If you can't use a Typescript server in your IDE, you can optionally generate a gql/graphql-env.d.ts by running this command.
+While this starterkit is in active development, fixing some UI bugs or unfinished components may not be a priority.
 
-```bash
-yarn generate:output
-```
+This starterkit is meant to serve two purposes:
 
-This command will also run `gql.tada turbo` which will generate a cache file that should also be commited. This cache file will speed up inference for new users who just checked out a new branch.
-More info [here](https://gql-tada.0no.co/devlog/2024-04-15)
+1. Provide best practices for starting new projects with Contentful and Next.js
+2. Provide a demo site and a playground to test new features released in Next.js and Contenful
 
-## NextJS Docs
+You are free to use the starterkit as a template to start new projects, but you can also pick and choose which reference implementations you like and copy them into your own project.
 
-To learn more about Next.js, take a look at the following resources:
+The demo site will evolve as we strive to demostrate more Next.js capabilities, but so will the Contentful part as Contentful adds more features (Contentful Studio, Taxonomy, etc)
 
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+Some features are going to be implemented just enough to demonstrate the concept in a demo, other features may be relying on particular infrastructure like on Vercel, it will be a balancing act.
 
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js/) - your feedback and contributions are welcome!
+Our commitment is to support majority of users and let them opt in, remove or modify certain functionality if they don't share the same infrastructure or feature set. We will provide documentation and guidance how to do that
 
-## Deploy on Vercel
+## Contributors
 
-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
-
-Check out our [Next.js deployment documentation](https://nextjs.org/docs/deployment) for more details.
+This project is open-source under MIT license and accepts contributions, if you have any feedback, please create a discussion or an issue on Github.