🚀 Next.js | Tailwind | TypeScript – TEMPLATE

Related Articles

• Toggle Vision 👀 — A LinkedIn post by Claire Sylvester (template creator) exploring the thinking behind grid toggling UX.

Table of Contents

• Prerequisites
• Getting Started
• VS Code Setup
  • Required Extensions
  • Additional Recommended Extensions
• Editor Configuration
• Version Management
  • Node.js Version
  • Yarn Version
• Styling Configuration
• Package Versions & Dependencies
  • Core Technologies
  • Styling & UI
  • Development Tools
  • Type Definitions
• Scripts
• Grid Overlay Toggle
  • Breakpoints Configuration
  • Layout Root (Dynamic SCSS Variables)
  • Grid Calculations
  • Layout SCSS
  • Grid Overlay SCSS
  • Component Structure
  • GridOverlayToggle Component
  • Implementation

Prerequisites

Getting Started

1. Clone the repository:

git clone git@github.com:CFsylvester/next.js-tailwind-typescript-TEMPLATE.git [your-repo-name]
cd [your-repo-name]

2. Set up Node.js version:

# Set Node.js version (if using nvm)
nvm use

3. Install dependencies:

yarn install

4. Run the development server:

yarn dev

Open http://localhost:3000 with your browser to see the result.

VS Code Setup

When you first open this project in VS Code, you'll automatically be prompted to install the recommended extensions in the bottom right corner. You can also install all recommended extensions at once:

1. Open the Command Palette Cmd/Ctrl + Shift + P
2. Type "Show Recommended Extensions"
3. Click "Install Workspace Recommended Extensions" (the cloud icon in the top right)

Required Extensions

• Prettier - Code formatter - Code formatting
• ESLint - JavaScript/TypeScript linting
• Tailwind CSS IntelliSense - Intelligent Tailwind CSS tooling

Additional Recommended Extensions

• PostCSS Language Support - Modern CSS syntax highlighting
• Auto Rename Tag - Automatically rename paired HTML/JSX tags
• Path Intellisense - Autocomplete filenames
• npm Intellisense - Autocomplete npm modules
• TypeScript Next - Latest TypeScript features

Editor Configuration

This project includes a .vscode folder with shared settings for VS Code users. These settings will:

• Set Prettier as the default formatter
• Enable format on save
• Enable ESLint auto-fix on save
• Require a Prettier config file to be present
• Enable enhanced Tailwind CSS IntelliSense features

These settings ensure that:

• All code is automatically formatted on save using Prettier
• ESLint problems are automatically fixed when possible
• The project's Prettier configuration is always used
• Tailwind CSS IntelliSense provides:
  • Intelligent CSS class completion
  • Syntax highlighting for Tailwind classes
  • CSS class suggestions in template strings
  • Proper validation of Tailwind classes
  • Support for custom class attributes
  • Quick suggestions in JSX/TSX files

Version Management

This project uses:

• .nvmrc for Node.js version management (currently set to v20)
• engines in package.json to enforce Node.js (>=20.0.0) and Yarn (>=1.22.0) versions
• packageManager field in package.json to specify exact Yarn version (1.22.22)

Node.js Version

To automatically use the correct Node.js version:

• Run nvm use in the project directory

Yarn Version

The project is configured to use Yarn 1.22.22. When you run yarn install, it will verify that you're using a compatible version of Yarn. If you have an incompatible version, Yarn will show an error message indicating which version you need to use.

Styling Configuration

Core styling configuration files:

• tailwind.config.js - Configuration including:

  • Custom breakpoints
  • Color palette
  • Custom shadows
  • Screen sizes

• src/styles/globals.scss - Global styles including:

  • Grid layout system
  • Base styles
  • Tailwind imports

Package Versions & Dependencies

Core Technologies

• - React framework for production-grade applications
• - JavaScript library for building user interfaces
• - Adds static typing to JavaScript
• - JavaScript runtime
• - Utility-first CSS framework
• - CSS preprocessor for enhanced styling
• - CSS transformation tool
• - Module bundler (built into Next.js)

Styling & UI

- Automatically adds vendor prefixes to CSS rules

Development Tools

- Linting utility for JavaScript and TypeScript

• - Next.js specific ESLint rules
• - Disables ESLint rules that conflict with Prettier

- Code formatter for consistent code style

Type Definitions

• - TypeScript definitions for Node.js
• - TypeScript definitions for React
• - TypeScript definitions for React DOM

Scripts

• yarn dev - Run development server
• yarn build - Build for production
• yarn start - Start production server
• yarn lint - Run ESLint
• yarn lint:fix - Fix ESLint errors
• yarn format - Format code with Prettier
• yarn check-format - Check code formatting

Grid Overlay Toggle

Breakpoints Configuration

The grid system uses the following breakpoints (defined in tailwind.config.cjs):

 screens: {
  xs: '320px', //  4 cols
  sm: '480px', //  4 cols
  md: '592px', //  6 cols
  lg: '784px', //  8 cols
  xl: '976px', // 10 cols
  '2xl': '1168px', // 12 cols
  '3xl': '1360px', // 14 cols
  '4xl': '1552px', // 16 cols
}

Layout Root (Dynamic SCSS Variables)

The grid system relies on dynamic scss variables updated at the above breakpoints to coincide with a responsive layout that is always divisible by multiples of 2. These dynamic, responsive, variables are used in both the .layout and [data-grid-overlay] scss selectors.

:root {
  // dynamic variables
  --layout-cols: 4;
  --layout-padding: theme('spacing.4');

  // hardcoded gap
  --layout-gap: theme('spacing.4');

  // clamp layout col width
  --layout-col-width: clamp(
    60px,
    calc(
      (100vw - (2 * var(--layout-padding)) - ((var(--layout-cols) - 1) * var(--layout-gap))) /
        var(--layout-cols)
    ),
    124px
  );

  @screen md {
    --layout-cols: 6;
    --layout-padding: theme('spacing.6');
  }

  @screen lg {
    --layout-cols: 8;
    --layout-padding: theme('spacing.8');
  }

  @screen xl {
    --layout-cols: 10;
    --layout-padding: theme('spacing.10');
  }

  @screen 2xl {
    --layout-cols: 12;
    --layout-padding: theme('spacing.12');
  }

  @screen 3xl {
    --layout-cols: 14;
    --layout-padding: theme('spacing.14');
  }

  @screen 4xl {
    --layout-cols: 16;
    --layout-padding: theme('spacing.16');
  }
}

Grid Calculations

With a hardcoded variable of --layout-gap: theme('spacing.4') (16px), the grid remains fully responsive and divisible by multiples of 2.

• Responsive Columns & Padding:

  • xs (320px): --layout-cols: 4; / --layout-padding: theme('spacing.4') (16px)
  • sm (480px): --layout-cols: 4; / --layout-padding: theme('spacing.4') (16px)
  • md (592px): --layout-cols: 6; / --layout-padding: theme('spacing.6') (24px)
  • lg (784px): --layout-cols: 8; / --layout-padding: theme('spacing.8') (32px)
  • xl (976px): --layout-cols: 10; / --layout-padding: theme('spacing.10') (40px)
  • 2xl (1168px): --layout-cols: 12; / --layout-padding: theme('spacing.12') (48px)
  • 3xl (1360px): --layout-cols: 14; / --layout-padding: theme('spacing.14') (56px)
  • 4xl (1552px): --layout-cols: 16; / --layout-padding: theme('spacing.16') (64px)

• Clamp Layout Column Width:

--layout-col-width: clamp(
  60px,
  calc(
    (100vw - (2 * var(--layout-padding)) - ((var(--layout-cols) - 1) * var(--layout-gap))) /
      var(--layout-cols)
  ),
  124px
);

This expression dynamically adjusts the column width based on the current --layout-padding and --layout-cols values at each breakpoint.

Layout SCSS

A responsive grid container that adapts to the dynamic variables defined in the layout.scss :root. It is utilized on the main element in the server rendered layout.tsx found in the app directory.

.layout {
  @apply grid
    h-full
    justify-center
    gap-x-[var(--layout-gap)]
    px-[var(--layout-padding)]
    grid-cols-[repeat(var(--layout-cols),var(--layout-col-width))];

  > .module {
    @apply h-fit z-0;

    &:not(:only-child) {
      @apply py-module;
    }

    &:only-child {
      @apply my-auto;
    }
  }

  //... &[data-grid-overlay] logic below
}

Grid Overlay SCSS

A purely css driven grid overlay that coincides with the layout class and it's breakpoints. When the data-overlay-grid is set to active, the grid overlay fades into visibility. It is dependent on being used on the same element as the .layout class. This is utilized on the main element in the server rendered layout.tsx found in the app directory.

.layout {
  // ...layout logic above

  &[data-grid-overlay] {
    @apply mx-auto bg-repeat-x z-10;

    width: calc(
      var(--layout-cols) * var(--layout-col-width) + (var(--layout-cols) - 1) * var(--layout-gap)
    );

    background-image: repeating-linear-gradient(
      to right,
      rgba(255, 0, 0, 0.2) 0,
      rgba(255, 0, 0, 0.2) var(--layout-col-width),
      transparent var(--layout-col-width),
      transparent calc(var(--layout-col-width) + var(--layout-gap))
    );
    background-size: calc(var(--layout-col-width) + var(--layout-gap)) 100%;
    opacity: 0;
    visibility: hidden;
    transition:
      opacity 0.3s ease-in-out,
      visibility 0.3s ease-in-out;

    &[data-grid-overlay='active'] {
      opacity: 1;
      visibility: visible;
    }
  }
}

Component Structure

• GridOverlayToggle: A client-side button that:

  • Reads and toggles a data-grid-overlay attribute on the <main> element
  • Displays the active breakpoint label
  • Shows a grid icon with an active/inactive state

• [data-grid-overlay]: A purely CSS-driven overlay that:

  • Uses CSS variables (--layout-cols, --layout-col-width, --layout-gap, etc.) to match the current layout
  • Renders semi‑transparent columns across the viewport
  • Transitions in/out when data-grid-overlay="active" is set by the GridOverlayToggle

GridOverlayToggle Component

A client side button that triggers the css overlay grid. Updates the main element data-grid-overlay with the active state.

const [active, setActive] = useState(false);
const overlayRef = useRef<HTMLElement | null>(null);

// Grab the element with [data-grid-overlay] once on mount
useEffect(() => {
  overlayRef.current = document.querySelector('[data-grid-overlay]');
}, []);

// Update the attribute whenever `active` changes
useEffect(() => {
  if (overlayRef.current) {
    overlayRef.current.setAttribute('data-grid-overlay', active ? 'active' : '');
  }
}, [active]);

Implementation

Add the grid system to your server render layout found in layout.tsx within the app directory:

<body>
  {/* DEV GRID TOGGLE */}
  {devMode && <GridOverlayToggle />}

  {/* MAIN CONTENT */}
  {/* GRID OVERLAY relies on the layout class on <main> */}
  <main data-grid-overlay className="layout">
    {children}
  </main>
</body>