ReScript NextJS Starter

The ReScript NextJS Starter is an opinionated boilerplate that combines Next.js, Tailwind CSS v2, and the ReScript compiler to give you a preconfigured setup for building React apps in ReScript.

What is the ReScript NextJS Starter?

This template provides a starting point for projects that use Next.js as the React framework, Tailwind CSS for styling, and ReScript (a typed language compiling to JavaScript) for application logic. It outputs a Next.js application with ReScript compiled to .mjs files (ES6 modules) and includes basic ReScript bindings for Next.js APIs. It is maintained by a ReScript core team member and was created from learnings of building the ReScript Documentation Platform.

Key Features

• Full Tailwind v2 configuration — includes a basic CSS scaffold and production setup with purge-css and cssnano.
• ReScript + React — preconfigured with the @rescript/react dependency and compiles ReScript to ES6 .mjs files.
• ReScript bindings for Next.js — ships general bindings for Next.js functions, kept simple and adaptable to your app.
• Fast Refresh guidance — recommends interface files (.resi) for each page, or re-exporting components through plain pages/*.js files to keep Fast Refresh always working.
• CommonJS switch option — documented steps to change compiler output to CommonJS and .bs.js suffixes instead of ES6 .mjs.
• Special-character filenames — supports files like pages/blog/[slug].res but notes you cannot import these modules elsewhere due to ReScript module syntax limitations.
• Production build test commands — includes commands for building CSS separately via PostCSS and for running a production Next build on a custom port.

Who is it for?

• ReScript developers who want to bootstrap a Next.js project without spending time wiring up the compiler and Tailwind.
• Next.js developers curious about ReScript who want a working integration example plus bindings to copy.
• Teams building typed React apps that want a maintained boilerplate from a core team member with production testing guidance.

What can you do with it?

• Start a new ReScript + Next.js project — clone the template, run npm run res:start and npm run dev in separate tabs, and get hot-reload development.
• Build production CSS separately — use the provided PostCSS commands to debug the Tailwind pipeline with npx postcss styles/main.css -o test.css in dev or production mode.
• Switch module systems — follow the documented steps to compile to CommonJS instead of ES6 if your tooling requires .bs.js files.

How does it work?

The development workflow runs two processes: npm run res:start watches and compiles ReScript files, while npm run dev starts the Next.js dev server. For production, you build with npm run build (after uncommenting the target attribute in now.json) and serve with PORT=3001 npm start.

FAQ

Why are the generated .mjs files tracked in git?

Tracking compiled JavaScript output lets you sanity-check whether changes to ReScript code actually affect the generated JS, especially during major compiler upgrades. It also helps non-ReScript teammates review changes in pull requests; to opt out, remove the src mjs files and add src/**/*.mjs to your .gitignore.

How trustworthy is this template?

It was created through building the ReScript Documentation Platform, which itself runs on Next.js, and is maintained by one of the ReScript core team members. Updates are irregular and driven by demand, such as important changes in the Next.js bindings or dependencies.

Can I import modules with special characters in filenames?

You can create files like pages/blog/[slug].res, but you cannot reference those modules inside other modules because ReScript has no syntax for brackets in module paths. You also need an accompanying .resi interface file to comply with Fast Refresh rules.

What should I do about Fast Refresh not working?

Make sure you only export React components from files in the pages directory, and create .resi interface files for each page/*.res file. The recommended always-works approach is to put ReScript components in src and re-export them in plain pages/*.js files.

What if I prefer CommonJS modules?

Set package-specs to use commonjs with in-source: true and suffix .bs.js, then replace the src/MyResFile.mjs import paths in pages with the .bs.js counterpart. This template defaults to ES6 .mjs output.