Nue.js Tutorial: Building a simple Web App

Table of Contents

1. Introduction
2. Type of files in Nue.js
3. Directory Structure
4. Examples of Nue.js Code
5. Conclusion.

Introduction

Nue is a web framework that emphasizes standards to build content-focused websites. It's relatively new in the market and is already seen as a potential successor to popular frameworks that are bundled with complexity and endless fixes. Given its rapidly rising popularity, understanding it is of great interest to developers.

Understanding the Nue.js directory structure is key to effective development and maintenance. Let’s delve into the specific roles and contents of each file and folder within a typical Nue.js project.

Type of files in Nue.js

1. .md (Markdown Files): Used for content creation, allowing easy writing and editing of textual content.​
2. .css (Cascading Style Sheets): Define the visual presentation of your content.​
3. .html (HyperText Markup Language): Structure the content and layout of web pages.​
4. .dhtml (Dynamic HTML): Group-related components, functioning as mini-libraries. ​
5. .yaml (YAML Ain't Markup Language): Store configuration and metadata in a human-readable format.
6. Interactive islands: An interactive island is a small, self-contained piece of interactivity added to a mostly static webpage. For example, imagine a webpage that is mostly static. If we want to add a form (an interactive element), we would prefer to place it separately from the static content. We would code it inside a .dhtml file and then reference it from the static page. The dynamic .dhtml file is what we refer to as an interactive island.

Directory Structure

Here we will first outline the directory structure:

Root directory

Root directory directory that acts as the base of your application.

1. index.md: This is a markdown file that represents the homepage.
2. site.yaml This is a YAML file that contains application-wide settings.

@global directory

This directory houses styles and layout files that apply site-wide. it contains files such as:

1. layout.css: contains core layout styles that structure your site
2. layout.html: contains header and footer templates to maintain a consistent navigation experience.
3. typography.css: contains CSS styles for typography.

blog directory

The blog directory is dedicated to blog-related content, assets, and templates. It's important to note that other directories in a Nue.js project follow a similar structure to the blog directory. For this reason, we’ve used the blog directory as an example to explain the layout. Essentially, each folder corresponds to a specific URL path on your site, and its name typically forms part of the URL structure starting from the root. This consistency helps maintain an organized, intuitive structure across your project.

1. blog.yaml: holds blog-specific settings such as content collection name and included styles.
2. hero.html defines the header template for the blog posts, incorporating metadata like title, publication date, and author.

@library

Contains modular CSS files for reusable components.

assets directory

Directory for hierarchically storing your assets.

.dist

The output directory is where everything is collected after compilation and ready for deployment.

Examples of Nue.js Code

In this section, we will explore how to write code using the files listed above. The source code we will be using can be found on github.(https://github.com/nuejs/nue/tree/master/packages/examples/simple-blog) or by running:

nue create simple-blog

Once you have the code up and running, come back here, and let’s go over the code. Let's discuss the most important files in the code.

site.yaml

# yaml-language-server: $schema=https://json.schemastore.org/nuejs-site.json
globals: ["@global"]
libs: ["@library"]
view_transitions: true
native_css_nesting: true
inline_css: true
sections: true
title_template: "Emma Bennet / %s"
og_image: /img/og_emma.png
author: Emma Bennet
favicon: /img/favicon.jpg
description: Minimalist, designer, and UX developer
port: 8083
# OG image
origin: https://simple-blog.nuejs.org
og: /img/og.jpg
navigation:
  header:
    - Emma Bennet: /
    - Contact: /contact/
    - Media: /media
  footer:
    - © Emma Bennet: /
    - image: /img/twitter.svg
      url: //x.com/tipiirai
      alt: Twitter (X) profile
      size: 22 x 22
    - image: /img/github.svg
      url: //github.com/nuejs/nue/
      alt: Github Projects
      size: 22 x 22
    - image: /img/linkedin.svg
      url: //linkedin.com/in/tipiirai
      alt: LinkedIn profile
      size: 22 x 22

Let’s begin by taking a look at a sample site.yaml file. Its located at the root directory . In it, we define application-wide settings.

The global key-value pair is used to include the global styles from the @global directory. This includes .css files for things like layout and typography.

This is followed by several SEO-related key-value pairs, which include:

• title_template: Defines how the title will appear.
• og_image: Specifies the location of the image, which is important for social sharing (e.g., on Twitter).
• author: Metadata that gives the name of the author of the blog.
• favicon: Specifies the location of the favicon, which appears in the browser's menu bar.
• description: Provides the meta description of the blog page, useful for SEO purposes.
• port: A server directive that specifies which port to use for serving the site.
• navigation: Defines an array (you can look up arrays in YAML) containing two objects: header and footer. Each object contains an array of text and accompanying links. Think of this as the data required by the website for generating navigation elements.

layout.html

<header>
  <navi :items="navigation.header"/>
</header>
<footer>
  <navi :items="navigation.footer"/>
</footer>

layout. HTML defines the structure of the website. Mostly it provides a header and footer structure. It's situated at '@global/layout.html'. It references the data (arrays) we defined above on the site.YAML. This way we reuse the data if it's needed elsewhere.

The rest of the files in the @global are just a bunch of CSS files.

blog.yaml

This file helps us include CSS modules from either @global or @library.

The code below includes content.css, cards.css and motino.css into the blog page:

include: [ content, cards, motion ]

.markdown files

These are files that are written by content writers using markdown. We will only focus on the front matter. Front matter is like meta data for the blog. Lets see an example:

---
title: Practical strategies for using colors in CSS
credits: BalkanBrothers
thumb: img/colors-thumb.png
og: img/colors-2.jpg
date: 2024-11-23
---

The above is metadata for the blog. It's given just before starting out the blog itself and in the above format.

hero.html

This file describes the structure of the blog's hero section ( the title, dates, and other data above the blog). It's templated using curly braces '{}' so that it can be reused by fetching that template data from the blog's metadata markdown shown above.

how blogs work in Nue.js

• Folder Name: The name of the blog folder forms the first part of the URL. This makes the folder name important for SEO and URL organization. For example, if the folder is named tech, the URL will start with yourdomain.com/tech.
• Markdown Files: Inside the folder, each .md file represents a single blog post. The name of each Markdown file will become the path of the URL. For example, if there is a file called first-post.md, the URL for that blog post will be yourdomain.com/tech/first-post.
• hero.html: The hero.html file inside the blog folder is a template used to define the header for all the posts in that folder. It includes meta-information like the post title, publication date, author, and featured image. This template is dynamically populated for each post based on the metadata provided in the Markdown files.

Conclusion.

Nue.js is a simple and efficient web framework that promotes a clear separation of concerns, allowing content creators and developers to have well-defined roles. It simplifies the development process by minimizing complexities commonly found in other web frameworks. With the guidance provided in this tutorial, you now have a clear understanding of how to set up and code a basic Nue.js web application. Happy coding!

Frequently Asked Questions