Skip to content
Sign inJoin waitlist

Troubleshooting — Balancee Next.js

Most problems with this Next.js template come from a content typo, a missing image or a form variable not set on the host. Those answers come first.

Then come the questions buyers ask most.

npm install fails, or the site behaves oddly after an update. Delete node_modules/ and package-lock.json, then npm install again. Check that node -v is 20.9 or newer.

Port 3000 is already in use. npm run dev -- -p 3001, or stop whatever holds the port.

npm run dev or npm run build stops with “Failed to fetch font Inter”. The font is downloaded from Google Fonts when the site builds (and the first time the development server runs), and the message ends with “Please check your network connection”. Connect, check your proxy or firewall, and run it again. To build without that download, host the font yourself with next/font/local (Making it look like your brand).

Module not found: Can't resolve '@/content/…' The path or the file name is wrong. @/ means src/, so @/content/site is src/content/site.ts. File names are case-sensitive on the servers that build your site, even when they are not on your laptop.

Property 'x' is missing in type … A content item lacks a field that src/content/types.ts requires. Your editor names the file and the line; add the field, or mark it optional in the type. A service, for example, needs intro, whatWeDo, offered and process, and a case study its four sections (Editing the content).

Cannot find name 'PageProps' (or 'LayoutProps') from npx tsc --noEmit. Next.js generates those types into .next/. Run npm run dev or npm run build once (or npx next typegen), then check again.

The build fails after I deleted or renamed a case study. Home picks six case studies by their slug (caseStudies in src/content/pages/home.ts: cards, spotlight and recent). A slug that no longer exists stops the build: change it there too.

An image does not appear. The file must be in public/images/ and the content must refer to it as /images/<file>: same spelling, same extension, no public in the path. A photo from another address needs its host in images.remotePatterns in next.config.ts.

A photo is cropped in the wrong place. Every photo sits in a frame and is cropped to fill it, from the centre, and the frames change shape between phone, tablet and desktop. Crop the photo to the shape you want and keep the subject away from the edges (Editing the content).

A video doesn’t play, or only its photo shows. The demo’s videos play from the Pexels website: without a connection, behind a firewall that blocks it, or once Pexels moves the file, the band shows only its poster photo. Put your own MP4 in public/videos/ (Editing the content). The hero video plays at once and loops, the About clip plays while it is on screen and the review video plays when “Watch a review” is clicked; with “reduce motion” switched on in the system, the hero and the About clip stay on their photo, and some phones in power-saving mode don’t play videos by themselves.

The build fails but npm run dev was fine. The build is stricter: it checks the types and renders every page. Read the first error, not the last; it names the file. A common cause is a missing field in a content item (the development server doesn’t check types).

The form says “Something went wrong”. The provider rejected the request, or a variable is missing. The reason is in your host’s function logs (Vercel: the deployment’s Logs tab), after [forms] New message from the Balancee contact form could not be delivered (for the footer box, New newsletter subscriber). Check that the environment variables are set for the environment you deployed to, that FORM_PROVIDER names a provider that exists, and redeploy after adding them.

The contact form won’t send and a field shows a message. Name, Company and Email are required, and the e-mail must look like an address (name@domain.com). Phone, the service and the message can stay empty. The footer box needs only the e-mail.

The form says “Thank you” but nothing arrives. With FORM_PROVIDER=console (the default, also when the variable is missing) submissions are only written to the server log: set a provider (Forms). If you added a field named fax, rename it: that name is the hidden spam trap, and a submission that fills it is dropped.

“Other blogs” is missing under a post. No other post has the same category, and the block is left out then. Categories are matched exactly: “Business” and “business” are two categories.

A new post isn’t first on Blog or Home. Nothing is sorted by date: the site shows the posts in the order of src/content/collections/posts.ts, newest first in the demo. Put the new post at the top of the list.

Blog and Portfolio show only four items. That’s on purpose: four more appear each time the visitor scrolls near the end of the list. Every item is in the page’s HTML from the start. To change the number, set list.pageSize in src/content/pages/blog.ts or portfolio.ts.

Home shows only six services, or three posts. Home shows the first ones: services.count and blog.count in src/content/pages/home.ts. The Services and Blog pages show them all.

A new service doesn’t appear in the contact form. The form’s “I’m interested in …” choices are written out in contactForm in src/content/pages/shared.ts: add the name to options (Forms).

A legal link leads to the 404 page. The footer’s legal links are written in footer.legalLinks in src/content/site.ts, and the line under the contact form in formLegal in src/content/pages/shared.ts: when you rename a legal page’s slug, change both.

“Let’s talk” opens the home page of cal.com. bookingLink in src/content/site.ts is a placeholder. Point it at your own booking page, or at /contact.

The share image or title is the old one. Facebook, LinkedIn and X cache them. Use their debuggers to refresh, and confirm that site.url is your domain.

The logo loop or the hover motion doesn’t move. The visitor’s system (yours, if you see it) has “reduce motion” switched on, and the site honours it (Making it look like your brand). The logo loop stands still and the rows open at once; everything is still there.

The wordmark looks different when I open logo.svg on its own. public/images/logo.svg and logo-white.svg are text set in Inter, so a computer without Inter shows another font. Install Inter or convert the text to outlines in a design tool; the site itself draws the wordmark in Logo.tsx.

An AGENTS.md or a CLAUDE.md appeared in the project. Next.js 16.4 adds them when npm run dev runs next to an AI coding assistant (Install and run). Keep or delete them; the site doesn’t use them.

Can I use this template for a client? See License: that is the one place that answers it for your licence.

Can I remove the style guide, a whole page or a section? Yes:

  • the style guide: delete src/app/style-guide/;
  • a page: see Pages and sections;
  • a section: delete its line in the page file, for example <HomeTestimonials /> in src/app/page.tsx.

I don’t want a blog or a portfolio. Can I take them off? Yes: remove the page (Pages and sections), its menu entry and its footer links, and the sections that list it on Home (<HomeCaseStudies … />, <HomeBlog … />). The footer also lists the first five case studies (footer.caseStudyCount in src/content/site.ts): set it to 0, or remove that column in src/components/site/Footer.tsx.

Can I change the fonts to my brand’s? Yes: Making it look like your brand.

Do I need a CMS? No. Content is files you edit. Add one when somebody who does not use a code editor has to publish (Using a headless CMS).

Can I take online bookings? The buttons “Let’s talk” and “Book a Free Consultation” lead to bookingLink in src/content/site.ts: point it at your Cal.com, Calendly or other booking page. The contact form sends a message; you answer it yourself, or send it to your booking or CRM tool through the webhook provider.

Can I write the site in another language? All the copy is content, so write it in your language. Then set lang in src/app/layout.tsx (and locale in its openGraph and in src/lib/meta.ts), the date format in src/lib/format.ts ("en-US"), and the interface words (“Main”, “Mobile”, “Menu”) in src/components/site/Header.tsx. The template has no language switch or language-based routing.

Does the site need a cookie banner? As shipped, the template sets no cookies and loads no third-party scripts: the font is served from your own domain. The demo’s three videos are loaded from Pexels until you replace them with your own files. Anything you add (analytics, an embedded booking widget, a chat) is yours to declare.

Can I show dates in another format? Yes. Post dates (“Feb 21, 2024”) and the legal pages’ “Last updated” come from formatDate in src/lib/format.ts.

Can I sell a site I build with this? Building sites for clients is what the licence is for; reselling the template itself as a template is not. The licence has the exact wording.

Will it work with Tailwind plugins, shadcn/ui, or my component library? Yes. It is a standard Next.js + Tailwind CSS 4 project; add packages as usual. The design tokens are plain CSS variables, so other libraries can read them.

How do I update to a new version of the template? Download the new release and copy your src/content/, public/, your icons and your theme.css into it. Then re-apply any component changes you made. CHANGELOG.md lists what moved.

Can you customise it for me, or build my site? Yes. Marcframe, the studio behind this template, updates templates to your needs (brand, content, new pages and features), builds custom templates and designs new websites. Get in touch at marcframe.com/contact or hire us on Contra.

Something is broken and none of this helps. Support and updates: https://framebrick.co/support. Send the page, the browser, and the error text or a screenshot: it makes the answer much faster.