This describes the proposed structure for version 3.0 (see History for why this version is numbered as it is). This structure is a combination of what worked in Dskate and SES.

None of this is implemented in the Drive installer. Also note that this is still a very rough draft.

File Structure

Assets

Source files are separated into packages. Default packages are:

  • assets/drive (click-to-edit and admin bar)
  • assets/src (default theme, Vue components, utilities--especially for working with the Drive API).

Compiled files are sent to:

  • assets/css
  • assets/js

Build Files, Formatting Files, Linting Files

At the project root are

  • Files used to get third-party packages (e.g. package.json, bower.json)
  • Files used to enforce code style
  • Files used for building package files and putting them into their respective folders

  • assets/
    • package-name/
    • css/
    • js/
  • .editorconfig
  • .eslint.js
  • .gitignore
  • gulpfile.js
  • package.json

Package Structure

This currently applies mostly to drive and src.

In each package folder, file types are separated by type into different folders (e.g. assets/package-name/scss). Where appropriate, each of these folders has:

  • an index file
  • configuration files (e.g. webpack config, tailwind config)
  • when code-splitting, files for other site sections or pages (e.g. shop.js, applicationForm.js)

Due to the possibility of naming conflicts in Proposal 1, I've included a second proposal.

Index File, Proposal 1

Each index file name is what ends up in the compiled folders.

assets/package-name/js/package-name.js becomes assets/js/package-name.js

This matches what was discussed before. However, for each project where there is a name conflict, one index file must be renamed. Because different people make different decisions in different projects, the way this is solved will vary.

Index File, Proposal 2

Where possible, this structure is used instead:

  • assets/package-name/js/index.js (source)
  • assets/package-name/index.js (compiled)

Where this is not possible (e.g. assets/theme/css/ contains source files), a new folder should be made called "minified" (if one doesn't exist already). If the theme comes with its own build files, the name of this folder is determined by what those build files are expecting.

  • assets/package-name/
    • scss/
      • indexScss.scss
    • js/
      • index.js
      • sectionOrPageName.js
      • webpack.common.js
      • webpack.dev.js
      • webpack.prod.js
    • css/
      • index.css

The Default Theme (src package)

scss

bootstrap-custom contains:

  • bootstrap.scss
    • imports bootstrap from node_modules
    • allows you to exclude default bootstrap components (e.g. badges)
    • imports bootstrap overrides from the same folder (e.g. variables)

js

If a framework is being used, it will be in its own folder (e.g. assets/src/js/vue, assets/src/js/react).

Note: structure will be taken mostly from Dskate

  • assets/src/
    • scss/
      • bootstrap-custom/
        • variables.scss
        • bootstrap.scss
      • indexScss.scss
    • js/
      • vue/
        • forms/
        • plugins/
      • utilities/
        • isMobile.js
      • sectionOrPageName.js
      • index.js
    • css/
      • components/
        • theme-overrides.css (example)
      • index.css

The Drive Package

Contains click-to-edit files, admin-bar styles, and theme overrides needed so that these display properly.

  • assets/drive/
    • css/
      • base.css
      • custom.css
      • index.css
    • js/
      • functions.js

The Theme Package (assets/theme)

This is where third-party theme files go. The structure of this directory varies depending on the structure of these themes.

It is called theme--as opposed to theme-name--for two reasons:

  • For each project, the theme rarely changes
  • This makes it easier to find the theme files, especially in older projects where admin panel assets are stored in the same folder as site assets.

History

To make it easier to document legacy projects, each pattern of building the assets folder will be split into versions.

Please note that these versions are currently not listed what is listed in the package.json file. If a project fits a pattern, feel free to add it.

Version 1.0

  • This describes the front-end before these files became part of the main repo.
  • Source files are in resources, and compiled/minified files are in public
  • When moving these files over FTP, example mappings include:
    • public/assets => project-web-root/assets
    • public/assets => project-web-root/project-name
    • public/assets => project-web-root/assets/theme

Version 2.0

  • The assets folder contains both source files and compiled files.
  • Examples of source file directories: assets/drive, assets/main, assets/theme.
  • Examples of compiled file directories: assets/css, assets/js.
  • Gulpfile, package.json, and other linting and building files are in the project's root directory.
  • Different projects have slightly different versions of v2.0
  • An incomplete version of this is what is currently in the Drive system

Version 3.0

  • This is the version proposed in this documentation. It improves on the structure established in v2.0.