How to setup a Next.JS app without create-next-app

15.03.2024

Introduction

Web development is a very vast subject and there is a lot of options for developpers. For a couples of years now javascript has become a standard in web dev and a lot of stack has been built on top of it, the most popular is probably the MERN stack (MongoDB, ExpressJS, React, NodeJS).

This stack uses React, this is a javascript front-end framework and there is a tons of javascript framework out here. When I say a lot, I mean A LOT, I think there are as much javascript framework as there are javascript developpers. OK, maybe not this much but you got the idea. A popular one is React this is a framework maintained by Facebook (Meta if you will) in my opinion it is maintained by a huge company with skilled developpers (i guess) so we can expect it to be a reliable framework. That is why I use it anyway and the fact that there is a lot of documentations, tutorials and help online for beginners. Now React is good and all but there is something better NextJS this is a React framework, yeah... a framework of a framework, don't ask questions.

The purpose of this post is not to explain what is React nor Next and why they're good framework, it is just to explain how to create a basic Next app. When it comes to JS framwork there is a huge chance that a package exist to create a default project for it, Next does not escape the rule, the create-next-app command will get you up and running with a basic app on the folder you specified, but i think it is good idea to understand, at least one time, what this command do and how it work under the hood. Or maybe you just like to do everything from scratch, which is honorable.

Installing dependencies

First let's create a folder to hold our app, somehting like next-starter and navigate to it, in the terminal:

$ mkdir next-starter
$ cd next-starter

NVM

Now, React and Next are built with NodeJS, wich means we need node installed on our macine. If you don't have it, I recommend you to use nvm (Node Version Manager), to install it use the command:

$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

Check the github page of nvm for troubleshooting, now you might have to restart your terminal for the installation to take effect.

NodeJS & NPM

Next, we need to install node and npm (node package manager) in order to install node packages, to install the latest version :

$ nvm install node

Basic npm project setup

We could use the command "npm init -y" to create a default npm project but let's do it ourselves. Create a file named package.json, this is a JSON file that will hold the name, version and description of our app and all the dependencies it uses.

{
  "name": "starter",
  "version": "1.0.0",
  "private": true,
  "scripts": {
    "dev": "next dev",
    "build": "next build"
  },
  "dependencies": {
    "next": "^14.1.0",
    "react": "18.2.0"
  }
}

You can here change the name and version of your app and add any dependencies. The scripts will let us run the app either in dev mode or produciton (build) mode. Now you might be asking, what if there is a new version of Next or React, well, when you will install the dependencies, npm will automatically upgrade some package (due to the ^ before the version number) without any flags, and it can cause conflict or error since your app was developped on a specific version. This is why we use a package-lock.json file to store an exact, versioned dependency tree. This way you can guarantee the dependencies for other developers, this file will be automatically updated when npm upgrade a packages in any way.

{
  "name": "starter",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "starter",
      "version": "1.0.0",
      "dependencies": {
        "next": "^14.1.0",
        "react": "18.2.0"
      }
    }
  }
}

Project structure

Create a folder named src at the source of your project, it will hold all the source files of your app and it's a good practice. In Next.JS page urls are constructed based on folder structure inside an app folder. So create a new folder named app inside your src folder.

Create a piblic folder to hold every static assets like icons, images, this way you will be able to refer to it in your page as /logo.png for example.

Create your first page

Now you can create a page, for that create a file called page.js inside src/app/, this file will be associated with the route /. This page should export a React component, for that add the following code:

export default function Home() {
  return <div>Hello World!</div>;
}

In order to test yout application, you need to install the dependencies list in the package.json file, for that run the command

$ npm install

Next you can run in development mode by running the command:

$ npm run dev

And you can see your site running in localhost:3000 by default. Check it you should see you Hello World page.

When running Next.js in development mode, we also get following benefits:

Auto compilation and bundling
React fast refresh
Static generation and server side rendering of /app
Static file serving through /public
hot reloading on file update

Adding Layout

If you've tried your app you might see that Next generated a layout.js for you, if not create it. We will modify a little bit what Next generated:

import './globals.css'
import { Inter } from 'next/font/google'

const inter = Inter({ subsets: ['latin'] })

export const metadata = {
  title: 'Start App',
  description: 'Next App starter template',
}

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body className={inter.className}>{children}</body>
    </html>
  )
}

You can also create two file, globals.css wich will hold the css shared by the whole web app and another file named homepage.module.css wich will hold the css for the home page.

The purpose of layout.js is to create a shared structure for every pages. On every website there is some content that appears on every pages like navbar, footer, logo or anything else. With layout you can create an html root structure and that will be the same and just add the rest of the page that is contain in the page.js file.

We've also specified some metadata like the website title and imported a custom Font to use the Next font optimization feature.

If you've followed along you project folder should look something like this:

next-starter/
├─ node_modules/
├─ .next/
├─ public/
├─ src/
│  ├─ app/
│  │  ├─ globals.css
│  │  ├─ homepage.module.css
│  │  ├─ layout.js
│  │  ├─ page.jsx
├─package.json
├─package-lock.json

Going further

If you to add any page just add a folder in the app directory. For example if you create a folder named about and put a page.js inside it when you will naviagte to localhost:3000/about it will load the content of you page.js inside the about src/app/about (also you can create a about.module.css file to style this page). I strongly recommend you to check the Next tutorial for learning the basics of Next.JS, it is consise and clear.

Conclusion

Now you know how to create a Next basic project, the structure and process is basically the same for any javascript project and if you want to speed up your development process for your future project i've made a Github Repo with this exact Next Starter folder that you can fork to your own github and clone whenever you start a new app.

I hope this post helped you, thanks for reading through the end, maybe in a future post i will explain how you can deploy a Next Application like this website you're a reading on, I mean, my website.