Guides and References
Guide: Creating a New Next.js Project

Guide: How to Create a New Next.js Project

Part 1. Create a New Next.js Project

Open a Terminal

Open a terminal on your computer. On Windows, you can open a terminal by pressing the Windows key and typing "cmd" and pressing Enter.

Navigate to the Desired Directory

Change to the desired directory (folder) where you would like your project to be located. For example, if you want the projects in c:\cprg306, you would type the following commands:

c:
cd \
mkdir cprg306
cd cprg306
⚠️

Do not use a cloud drive (e.g., Google Drive, OneDrive, Dropbox) for your project. This can cause problems with the node_modules folder because it contains thousands of files and will cause the cloud drive to sync constantly.

Create the New Next.js Project

Enter the following command in the terminal to create a new Next.js project:

npx create-next-app@latest
😣

If you receive an error like the following: npm ERR! enoent ENOENT: no such file or directory, lstat 'C:\Users\[profile-name]\AppData\Roaming\npm', you may need to create a folder called npm in your Windows AppData\Roaming folder. You can do this by typing the following command in the terminal: mkdir %AppData%\npm

The create-next-app application will scaffold (create/generate) a new Next.js project. For the assignments, here is how you must answer the questions:

QuestionAnswer
What is your project named?cprg306-assignments
Would you like to use TypeScript?No
Would you like to use ESLint?Yes
Would you like to use Tailwind CSS?Yes
Would you like to use src/ directory?No
Would you like to use App Router? (recommended)Yes
Would you like to use Turbopack for next dev?Yes
Would you like to customize the default import alias?No

Use the arrow keys to select the desired answer, then press Enter.

Note: It is also possible to use the following non-interactive command to create a new Next.js project: npx create-next-app@latest cprg306-assignments --js --eslint --tailwind --no-src-dir --app --turbopack --import-alias "@/*"

Close the Terminal

You can close the terminal now. From now on, you will only use the terminal in VS Code.

Part 2: Running Your Next.js Application

Open the New Project in VS Code

Open the project in VS Code using File -> Open Folder... and select the [app-name] folder that you have just created.

Open the terminal in VS Code

You can open the terminal in VS Code by going to View -> Terminal or by pressing Ctrl-` (backtick - the key is usually located at the top left of the keyboard).

Install Dependencies

In the terminal, run the following command to install the dependencies for the project:

npm install

Start the Development Server

Run the following command to start the Next.js development server:

npm run dev

Open the Application in Your Web Browser

After running npm run dev, a link to your local application (typically http://localhost:3000) will appear in the terminal. You can Ctrl-click this link to open it directly in your default web browser. If this doesn't work, you can manually open your preferred web browser and enter http://localhost:3000 in the address bar. You should see your new Next.js application running!

Stopping Development

When you are finished coding for the day and wish to shut down VS Code, you should shutdown the development server. In the terminal, press Ctrl-c to shut it down.

Part 3: Push Your Project to GitHub Using GitHub Desktop

Open GitHub Desktop

Add Local Repository

Click on File -> Add local repository... and choose the folder for [app-name].

Publish repository

Click the button "Push repository". It is recommended to keep the GitHub repository the same name as the app name.

Uncheck "Keep this code private" to allow the instructor access to your repository. Private repositories will be given a grade of 0.

Click the button "Publish repository".

View the Repository Code

In a browser, navigate to https://github.com/[GitHub-username]/[app-name] to see the code in your browser.

Part 4: Optional Files

While working on your project, you may want to consider adding a couple of optional files that can significantly impact how others view and use your work. The LICENSE file is crucial if you decide to open source your project; it tells others what they can and cannot do with your code. On the other hand, a well-crafted README.md serves as the front page of your project: it provides visitors with information about the project, how to install and use it, and how to contribute. Including these files can help build a community around your project and ensure that everyone understands the terms of use and collaboration.

Adding a LICENSE File

To open-source your project, it's important to choose an appropriate license. A license dictates how others can use, modify, and distribute your code. Here's how to add a LICENSE file:

To add a LICENSE file to your Next.js project using Visual Studio Code (VS Code), follow these steps:

  1. Open Your Project in VS Code:

    • Launch VS Code.
    • Open your project by navigating to File > Open Folder and selecting your project's directory.

  2. Create the LICENSE File:

    • Right-click on the explorer area in VS Code and select New File.
    • Name the file LICENSE.

  3. Choose a License:

    • Go to ChooseALicense.com (opens in a new tab).
    • Select a license that fits your project's needs. The MIT License is a popular choice for its permissiveness and simplicity. This website uses this license.

  4. Add the License Text:

    • Copy the full license text from the website.
    • Paste the text into your new LICENSE file in VS Code.

  5. Save the LICENSE File:

    • Save the file by pressing Ctrl + S on Windows or Cmd + S on macOS.

  6. Commit and Push Your Changes with GitHub Desktop:

    • Open GitHub Desktop and select your repository from the list.
    • You will see the LICENSE file listed as an uncommitted change.
    • Add a commit summary, such as "Add LICENSE file."
    • Click on Commit to main to commit the file to your main branch.
    • Click on Push origin to push your changes to the remote repository on GitHub.

Editing the README.md File

The README.md file is the first thing people see when they visit your repository on GitHub. It should be informative and concise. Here are some guidelines:

  1. Project Title:

    • Write a clear, descriptive title for your project.

  2. Description:

    • Explain what your project does and why it's useful.
    • Include any key features or benefits.

  3. Installation Instructions:

    • Provide a step-by-step guide to get your project running.

  4. Usage:

    • Show how to use your project, with code examples or screenshots.

  5. Contributing:

    • If you're open to contributions, explain how others can contribute.
    • Link to a CONTRIBUTING.md file if you have one.

  6. Credits:

    • Acknowledge any collaborators or sources of inspiration.

  7. License:

    • Mention the type of license you've chosen.
    • You can add a section like this:
    ## License
 
This project is open source and available under the [MIT License](LICENSE).

If you have edited README.md, don't forget to save the file and then use GitHub Desktop to commit and push your changes.

Guide: Cloning a Next.js Project RepositoryGuide: Coding Workflow