Troubleshooting — Tustel Next.js

Most problems come from a content file with a typo, a missing image or a form variable that was not set on the host. The answers below cover those first, then the questions buyers ask most.

Errors you may hit

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.

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.

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.

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 card or a gallery photo has the wrong shape. Project cards, covers, galleries and the photo at the top of a post take each photo’s own proportions, read from the file (src/lib/image-size.ts): a portrait cover makes a tall card, so crop the photo to the shape you want. If a card keeps its old shape after you replaced the photo, restart npm run dev. A photo from another address (a CMS) sits in a 4:3 box (3:2 for a post photo) until you pass its size (Using a headless CMS).

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 project enquiry could not be delivered. 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.

“Book a call” opens cal.com. That’s the demo’s placeholder. Put your own booking page (or /contact) in bookCall.href in src/content/site.ts.

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 header disappears, or doesn’t show on Home. On every page except Home and the 404 page, the header hides while you scroll down and comes back as soon as you scroll up. On Home it lies over the photo at the top and scrolls away; a solid one appears when you scroll back up past the client logos (Pages and sections). If you removed the client logos, see Pages and sections.

Nothing moves: the slideshows, the tickers, the counters. 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 slideshows and tickers stop, and the counters show their final number at once.

The Portfolio or the Blog shows only six items. That’s on purpose: more appear each time the visitor scrolls to the spinner under the list (four at a time on tablets and phones). Every item is in the page’s HTML from the start. To show more at once, see Making it look like your brand.

Questions

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 <BandSection … /> (the full-screen photo with a call to action) in src/app/page.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 show dates in another format? Yes. Post dates (“Apr 16, 2025”) 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.