Project Structure

Your new Hyas project generated from the create hyas CLI wizard already includes some files and folders. Others, you will create yourself and add to Hyas’ existing file structure.

Here’s how an Hyas project is organized, and some files you will find in your new project.

Directories and Files

Hyas leverages an opinionated, Hugo-based folder layout for your project. Every Hyas project root should include the following directories and files:

• assets - Your project assets (scripts, styles, images, etc.)
• config - Configuration files (Hyas, Hugo, PostCSS, etc.)
• content - Your project content (pages, posts, etc.)
• layouts - Your project layouts (partials, shortcodes, etc.)
• static - Your non-code, unprocessed assets (fonts, icons, etc.)
• package.json - A project manifest.

Example Project Tree

A common Hyas project directory might look like this:

• Directoryassets/scss

  • Directorycommon

    • _custom.scss
    • _variables-custom.scss
  • app.scss
• Directoryconfig

  • Directory_default

    • hugo.toml
    • module.toml
    • params.toml
• Directorycontent

  • _index.md
• Directorylayouts

  • index.html
• Directorystatic

  • favicon.svg
• package.json

assets/scss

It is a common convention to store your CSS or Sass files in a assets/scss directory, but this is not required. As long as your styles live somewhere in the assets/ directory and are imported correctly, Hyas will handle and optimize them.

The app.scss file is used to specify the CSS or Sass files to import (or use). Put your custom (S)CSS variables in common/variables-custom and custom (S)CSS code in common/_custom.scss.

config/_default/

The hugo.toml file includes Hugo configuration options for your Hyas project. Here you can specify taxonomies to use, build options, server options, and more.

The module.toml file specifies the Hugo mounts, logically linking node_modules directories to component folders (ex: assets, layouts) — making Hyas Integrations available in your Hyas project.

The params.toml file is where you set Hyas configuration options like e.g. options for themes and integrations.

See the Configuring Hyas Guide for details on setting configurations.

content/

The content/ directory is where you store content, organized in sections or page bundles (leaf bundles or branch bundles) and can contain page resources.

layouts/

Layouts are Hyas templates that define the UI structure shared by one or more pages.

static/

The static/ directory is for files and assets that do not need to be processed during Hyas’ build process. These files will be copied into the build folder untouched.

This behavior makes static/ ideal for common assets like images and fonts, or special files such as robots.txt and manifest.webmanifest.

You can place CSS and JavaScript in your static/ directory, but be aware that those files will not be bundled or optimized in your final build.

Tip

As a general rule, any CSS or JavaScript that you write yourself should live in your assets/ directory.

package.json

This is a file used by JavaScript package managers to manage your dependencies. It also defines the scripts that are commonly used to run Hyas (ex: npm run dev, npm run build).

There are two kinds of dependencies you can specify in a package.json: dependencies and devDependencies. In most cases, these work the same: Hyas needs all dependencies at build time, and your package manager will install both. We recommend putting all of your dependencies in dependencies to start, and only use devDependencies if you find a specific need to do so.

For help creating a new package.json file for your project, check out the manual setup instructions.