Web App Template

Welcome to an incredible full-stack web application template powered by Next.js! This template is crafted to ease the deployment of GDPR-compliant projects endowed with a Content Management System (CMS), database, user management, and a customizable UI. It serves as a full-fledged, ready-to-deploy foundation for your next project.

• Getting Started with Template Configuration
• Features
  • Database Setup
  • Social Login and User Management
  • UI Library
    • Homogenous Color Palette
  • Comprehensive Testing
  • State Management and Data Fetching
  • Form Handling
  • Multi-Language Support with SEO Optimization
  • Open Graph
  • Out-of-the-Box PWA Setup
    • favicons Script
    • next-pwa Integration
  • Prudent Routing Choice Ensures Stability
  • Embedded Sanity.io
    • Environment Configuration:
• NPM Scripts Explained
• Feedback & Support

Getting Started with Template Configuration

Welcome to the initial setup! Here’s a simplified guide to adjusting the essential elements in the template to match your project requirements:

1. Environment Configuration:

   • Copy the .env.local.example file as .env.local file.
   • Fill in the necessary values within the newly copied file.

2. Docker Development Setup:

   • Open the docker:dev section.
   • Modify the database name and port. Ensure the port number matches the one specified in your .env.local file.

3. PWA Configuration:

   • Navigate to pwa.config.mjs.
   • Update the theme color, app name, app icons, and splash screens as per your preferences.

4. Node Version:

   • Ensure you are utilizing the Node version specified in the .nvmrc file.

5. CSS Variable Prefix:

   • Go to src/ions/theme/constants.ts.
   • Alter the CSS_VARIABLE_PREFIX to your desired value.

6. Create Index Page

   • Head over to http://localhost:3000/admin.
   • Create a Page with the route "home" and add all required fields

7. Theme Adjustment (Optional):

   • Head over to src/ions/theme/index.ts for basic theme adjustments.
   • For more granular control, you may venture into src/ions/theme/palette.ts, although it's strongly discouraged. The existing palette has been meticulously optimized for various aspects including UI accessibility (a11y) support, and altering it may affect these optimizations.

By following these steps, you'll have personalized the template to a good extent, making it more aligned with your project's needs. Happy coding!

Features

Database Setup

⚖️ GDPR Compliance: The combination of Prisma, Postgres, and Docker facilitates GDPR-compliant data management practices by ensuring secure, structured, and well-documented data handling.

• Prisma: We utilize the robust Prisma database with pre-configured scripts via @prisma/client. Prisma offers a strong Object-Relational Mapping (ORM) layer for easy data access and manipulation.

• PostgreSQL: Paired with Prisma, we use Postgres as our database engine of choice, known for its reliability and feature set.

• Docker: For ease of local setup, we've configured a Docker container that runs Postgres. This ensures that you don't need to install Postgres locally, making it easier to manage your development environment.

ℹ️ You can start the database container using the docker:dev script in your package.json.

Social Login and User Management

⚖️ GDPR Readiness: The integration of Auth.js for social login and user preferences management is designed in adherence to GDPR guidelines ensuring user data privacy and consent management.

• Social Login: Integrated with Auth.js (formerly known as NextAuth) for seamless social login options.
• User Preferences: Includes a GDPR-ready Cookie Banner for user privacy.

UI Library

⚖️ GDPR Compliance: Utilizing Joy UI enables the creation of user-friendly interfaces, ensuring clear communication and consent collection in line with GDPR requirements.

• Core UI: Leverage the power of Joy UI, the next-gen UI library.
• Additional UI Elements: Material icons (@mui/icons-material).

Homogenous Color Palette

Crafting top-notch user experiences? That's our jam. So, we rolled out a homogenous color palette. It's not just about the looks - it's a strategic move to boost user understanding and make our interfaces robust.

• Consistent Accessibility: All 500-shade colors are AA compliant against both black and white.
• Optimal Text Visibility: The 500 shades are optimized to pair best with white text.
• Component Compatibility: Uniformity ensures a seamless fit across all components.
• Intuitive Gradients: Clear understanding of shades and hues aids in design decisions.
• Broad Hue Range: With 9 distinct hues and a neutral grey, we ensure diversity in design choices.
• Inter-hue Harmony: Consistent shading across hues guarantees a harmonious UI.
• Wide Compatibility: This palette is designed to blend seamlessly with varied UI elements and layouts.

By leveraging this palette, we're fusing design intuition with top-tier development to deliver a cohesive and user-centric product.

Comprehensive Testing

• Unit Testing: Jest for unit tests.
• Behavioral Testing: Cucumber.js for BDD.
• End-to-End Testing: Playwright for running Cucumber tests.

Links

• Gherkin Reference

State Management and Data Fetching

• SWR: For React hooks-based data fetching: SWR.
• Fetching: Use Axios for simplified fetching.
• Jotai: Minimalist atomic state management: Jotai.

Form Handling

• React Hook Form: Efficient and flexible form management: React Hook Form.

Multi-Language Support with SEO Optimization

Our platform ingeniously combines the power of next-i18next for user interface translations with a handcrafted solution for mapping localized MDX files. The latter is achieved by incorporating rewrites and redirects within the next.config.mjs, ensuring a seamless mapping of pages like "my/page/index.mdx" to EN ("/my/page") and "my/page/de.mdx" to DE ("/de/my/page"), with the flexibility to alter this default mapping as per project needs.

ℹ️ If your default language is German, you can change your "de.mdx" to "en.mdx".

• "my/page/index.mdx" to DE ("/my/page")
• "my/page/en.mdx" to EN ("/en/my/page")

This distinctive setup not only automates language mapping but also addresses SEO concerns proficiently. By generating canonical and alternate tags for both "x-default" and localized versions, we ensure optimal SEO performance, making the platform easily discoverable across different language-based search engines.

The fusion of next-i18next for UI translations and our unique MDX file mapping logic contributes to a robust, SEO-optimized, and user-friendly multi-language environment, making the platform highly accessible and engaging for a global audience.

Moreover, we have enriched our multi-language support with 16 meticulously hand-coded svg country flags, provided as react components, adding a visual cue to the language selection process.

Belgium China Czech Denmark Finland France Germany Italy Japan Netherlands Norway Poland Spain Sweden U.K. U.S.A.

Open Graph

We use Satori, an enlightened library that converts HTML and CSS to SVG or PNG, to automate the generation of Open Graph images and social cards.

• Seamless Integration: Comes preconfigured for Next.js.

• Wide Usage: Ideal for generating PNG images for Open Graph and social cards, making your web app more shareable and visually engaging on social platforms.

Out-of-the-Box PWA Setup

favicons Script

• Functionality: Generates favicons, splash screens, and a manifest file that are crucial for a polished web app. Additionally, it creates a React component that takes care of rendering all necessary meta tags and links in the header.

• Customization: The script works excellently out-of-the-box but can be customized via a pwa.config.mjs file.

next-pwa Integration

Further enhancing our PWA setup, we also integrate Next PWA, a zero-config PWA plugin powered by workbox and optimized for Next.js.

• Zero-Config: No need to manually register or generate a service worker, as next-pwa takes care of this for you.

• Performance: Maximizes Lighthouse score and optimizes both precache and runtime cache.

• Flexibility: Offers workbox configuration options for those who need more control, without the need for a custom server.

By integrating next-pwa, we provide an all-in-one solution that handles all PWA requirements, giving you complete offline support, optimized caching, and more.

Together with the favicons script, you get a comprehensive, yet customizable, PWA setup that allows you to focus on your core app functionality.

Prudent Routing Choice Ensures Stability

In the evolving landscape of Next.js, the emergence of app router has certainly piqued interest. However, amid the ongoing adaptation phase of many libraries towards React's server-side components, we've opted for the original pages router from Next.js over the app router. Our decision stems from a desire to avoid being prematurely entangled with nascent solutions that necessitate extensive use of "use client," which could undermine the intended benefits.

By aligning with well-established, thoroughly tested libraries, we uphold a commitment to stability and reliable functionality over chasing the bleeding edge. The libraries encompassed in our setup are not only up-to-date and diligently maintained, but are also recognized as some of the top choices in the market. As these libraries evolve, so will our template, maintaining a dependable product that emphasizes best practices and rigorous testing. This pragmatic approach simplifies adoption, enhances reliability, and ensures our readiness to seamlessly transition as the ecosystem matures.

Embedded Sanity.io

We've adeptly integrated Sanity.io within the template, ushering in a robust Content Management System (CMS) that comes preconfigured with schemas for essential pages, navigation entries, addresses, and a blog, serving as exemplary setups. This integration not only facilitates the enrichment of other static pages with dynamic content but also lays a solid foundation for further content management endeavors, thus significantly enhancing the overall content management experience.

Environment Configuration:

• Duplicate the .env.local file.

• Populate the following new environment variables which are essential for Sanity integration:

  • NEXT_PUBLIC_SANITY_PROJECT_ID="XXX"
  • NEXT_PUBLIC_SANITY_DATASET="production"

  You can find these values on your Sanity management dashboard at https://manage.sanity.io.

Sanity's CMS is strategically tucked behind two layers of login security to ensure an extra level of protection:

1. App Admin Login:

   • Initially, log in as an admin to the app. This level grants access to the studio login portal.

2. Studio Login (Sanity):

   • Proceed to log into the Sanity studio to access and manage your content.

This dual login setup not only fortifies the security around your content management system but also provides a streamlined workflow for administrators and content managers alike.

With Sanity.io embedded within, managing content, including GDPR-related legal pages, blogs, or other static pages, becomes a streamlined, secure, and efficient process. This integration aims at providing a flexible yet secure environment for all your content management needs, aligning with GDPR standards.

NPM Scripts Explained

This section details a variety of NPM scripts included in the project to streamline development, building, and testing processes. These scripts simplify various tasks, ensuring a smooth workflow throughout the project lifecycle.

• build: Generates a production-ready build of your Next.js app.

• docker:dev: Spins up a Postgres container for development. Make sure you have Docker installed before running this script.

• dev: Runs the Next.js app in development mode.

• favicons: Generates favicons via a Node.js script. Check pwa.config.mjs for configuration options.

• prisma:client: Updates your Prisma client and database schema based on your .env.local variables.

• prisma:migrate: Runs migrations to update your local database schema.

• prisma:studio: Opens Prisma Studio, a GUI for your database.

• start: Starts the production server.

• test: Runs both Jest unit tests and Cucumber BDD tests.

• test:bdd: Runs feature tests using Cucumber.

• test:ci: Starts the server and runs BDD tests, designed for Continuous Integration.

• test:jest: Runs Jest unit tests.

• test:only: Runs only the Cucumber tests tagged with @only.

• vercel-build: Generates Prisma client, runs migrations, and builds the app. Meant for Vercel deployments.

Feedback & Support

We value your input. Reach out to us through these channels:

• Issue Tracker: Encountered a bug? Report it on GitHub Issues.