next.js-tailwind-typescript-TEMPLATE

🚀 Next.js | Tailwind | TypeScript – TEMPLATE

Dependencies Last Commit Maintenance

Next.js React TypeScript Node SASS Tailwind CSS Yarn License

</br>

Related Articles - [Toggle Vision 👀](https://www.linkedin.com/feed/update/urn:li:activity:7320859432408514560) — A LinkedIn post by [Claire Sylvester (template creator)](https://github.com/CFsylvester) exploring the thinking behind grid toggling UX. - [Re‑Toggled Vision: A Lean, SCSS‑First Grid Overlay](https://www.linkedin.com/pulse/retoggled-vision-lean-cssfirst-grid-overlay-claire-sylvester-jh5yc/) - A LinkedIn post by [Claire Sylvester (template creator)](https://github.com/CFsylvester) reworking the original "Toggle Vision" CSS grid overlay toggle.
Table of Contents - [Prerequisites](#prerequisites) - [Getting Started](#getting-started) - [VS Code Setup](#vs-code-setup) - [Required Extensions](#required-extensions) - [Additional Recommended Extensions](#additional-recommended-extensions) - [Editor Configuration](#editor-configuration) - [Version Management](#version-management) - [Node.js Version](#nodejs-version) - [Yarn Version](#yarn-version) - [Styling Configuration](#styling-configuration) - [Package Versions & Dependencies](#package-versions--dependencies) - [Core Technologies](#core-technologies) - [Styling & UI](#styling--ui) - [Development Tools](#development-tools) - [Type Definitions](#type-definitions) - [Scripts](#scripts) - [CI & Deployments](#ci--deployments) - [CI Workflows Includes](#ci-workflow-includes) - [Vercel Deploy Flow](#-vercel-deploy-flow) - [Grid Overlay Toggle](#grid-overlay-toggle) - [Breakpoints Configuration](#breakpoints-configuration) - [Layout Root (Dynamic SCSS Variables)](#layout-root-dynamic-scss-variables) - [Grid Calculations](#grid-calculations) - [Layout SCSS](#layout-scss) - [Grid Overlay SCSS](#grid-overlay-scss) - [Component Structure](#component-structure) - [GridOverlayToggle Component](#gridoverlaytoggle-component) - [Implementation](#implementation)

Prerequisites

Node.js Yarn VS Code

⚠️ Direct pushes to main are blocked by CI unless the commit message includes [override-main]. Use Pull Requests into main, or merge from staging.

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]
  1. Set up Node.js version:
# Set Node.js version (if using nvm)
nvm use
  1. Install dependencies:
yarn install
  1. 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

Editor Configuration

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

These settings ensure that:

Version Management

This project uses:

Node.js Version

To automatically use the correct Node.js version:

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:

Package Versions & Dependencies

Core Technologies

Styling & UI

Autoprefixer - Automatically adds vendor prefixes to CSS rules

Development Tools

ESLint - Linting utility for JavaScript and TypeScript

Prettier - Code formatter for consistent code style

Type Definitions

Scripts

CI & Deployments

Deploy with Vercel CI Checks

This template includes a built-in GitHub Actions workflow (ci.yml) that runs automatically on all pull requests and pushes to main and staging.

CI Workflow Includes

All CI checks must pass before merging into main or staging.
Preview deployments are automatically handled by Vercel for all branches and PRs.

🌐 Vercel Deploy Flow

Branch Environment Deployment
main Production ✅ Auto-deploy to prod
staging Staging ✅ Auto-deploy to preview/staging
feature PR Preview ✅ Deploy Preview via Vercel

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.

--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 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:

// check env vars
const devMode = process.env.NODE_ENV === 'development';
const isGridOverlayOverride = process.env.GRID_OVERLAY_OVERRIDE === 'true';

// show grid overlay if dev mode is true or if the grid overlay override is true
const showGridOverlay = devMode || isGridOverlayOverride;

return (
  <html lang="en" className={montserrat.variable}>
    <body>
      {/* DEV GRID TOGGLE */}
      {showGridOverlay && <GridOverlayToggle />}

      {/* MAIN CONTENT */}
      {/* GRID OVERLAY relies on the layout class */}
      <main data-grid-overlay className={'layout'}>
        {children}
      </main>
    </body>
  </html>
);
This site is open source. Improve this page.