Project Organization

The first thing to understand is how projects are organized in terms of the file system, that is to say, get to know which files are there and what are they for.

Most of the GobstonesWeb2 projects will be comprised of multiple files, and their organization will be explained in the corresponding README.md file. This document will explain the most common configurations.

Most of the projects that work as libraries are created from the gobstones-scripts project. That is, the structure of the project is based on one of the provided project structures of gobstones-scripts, in either one of:

  • library
  • cliLibrary
  • reactLibrary
  • noCode

Other projects that work as full fledge React applications are created using create-react-app while backend manager is created using payload. Other more strange projects may exist, like this guidelines project.

Some files though are general for any project. We will divide this section in parts where we will explain each

Files in different projects

Files present in all projects

Some files are present in every GobstonesWeb2 project.

All projects are based on TypeScript/JavaScript technologies, so they will all contain a package.json file. This file will contain information such as the package name, version and description, the repository and webpage, author information, exported information and dependencies.

Another file that will be present every time is the README.md file. This file contains information about the project itself, such as the project name and full description, how to install it and use it, how to develop and contribute to the project further on, and other useful information.

An additional file present at the root of the project is the LICENSE file, which contains the software license of the project. In most cases, this is the AGPL license version 3.

The CONTRIBUTING.md file holds information on how to contribute to the project.

The CHANGELOG.md file holds information of all the versions and changes to the project.

The .gitignore will also be an ubiquitous file that holds the information of folders and projects not to commit to the central repository.

Additionally to this files, you will find the files .prettier and .prettierignore, that holds the prettier configuration for the project files, along with the .editorconfig file, that does a similar thing.

You will also find the .czrc file, that hold the commitizen information, and the commitlint.config.js that holds the commitlint configuration.

Regarding folders, you will find the .github folder, that holds pull reques templates, issue templates and most importantly, the GitHub Action workflows. Also the .husky folder will hold the Git Hooks triggers in use. Finally the .vscode folder holds the add-ons and configuration that Visual Studio Code should use when opening this project.

Finally, code or important files will live in the src folder, while testing files will live at the test folder.

As a summary, we will find:

  • package.json
  • README.md
  • LICENSE
  • CONTRIBUTING.md
  • CHANGELOG.md
  • .gitignore
  • .prettier
  • .prettierignore
  • .editorconfig
  • .czrc
  • commitlint.config.js
  • .github
  • .husky
  • .vscode
  • src
  • test

Usual generated folders

Some folder's might act as generated folders in multiple (but not all) projects, and they are not present by default, but appear after a particular action had been executed in the project.

One of this is node_modules that appears when the dependencies are installed, dist that will usually hold the generated files after building, doc that will hold documentation generated by a particular tool, or even coverage that holds the testing code coverage for multiple projects.

This projects will not be added or uploaded to the central repository.

A summary of this includes:

  • node_modules
  • dist
  • doc
  • coverage

libraries and CLI libraries project files

The projects that are intended to be published as simple libraries or cliLibraries will usually contain a .eslintrc.js file that contain the configuration to ESLint.

The .npmignore file will hold configuration on which elements to publish, that is, which files will be present when someone downloads the library to use it.

Present files increase with:

  • eslintrc.js
  • .npmignore

Regarding the code, you will find TypeScript (.ts extension) files inside both the src and test folders, with a src/index.ts that acts as a Barrel Pattern containing the main element to expose when someone wants to use the library through the API. In the case of CLI applications, you will also find a src/cli.ts, that holds the application that will be executed when running the library as a CLI application.

Inside the src folder, you may find multiple sub-folders, each one holding a sub-module or sub-section of the library. Each of this will contain one or more TypeScript files. In each folder you will find an index.ts file, that acts as an entry point of the submodule, holding the sub-module documentation and exports, following the Barrel Pattern.

In the test folder you may find the same folder structure that in the src folder, containing test files, either unit test or functional tests, ending in .test.ts.

The rest of the configuration of the project will be abstracted away through the use of @gobstones/gobstones-scripts, except that the project ejected any of the configuration files for customization. You will find the configuration for the library at the package.json file's config.gobstones-scripts key.

React libraries project files

React libraries are also created through @gobstones/gobstones-scripts and so will share the abstracted files, tool configuration at package.json and project structure as libraries and CLI libraries.

Additionally to those files, you will find at the root of your project a vite.config.js file, that configures Vite to run your storybooks, for easy development and documentation through the tool. An additional .storybook folder will contain the StoryBook configuration, while the stories folder will contain all stories.

In this projects, the main sub-folder at src is components that will hold all the project components. Each component is stores in a folder inside src/components, that has a pascal case name, and contains all files for such component, including code (in the form of a .tsx file), styles (using Sass) and other assets.

React applications project files

The main applications that we use are mostly React based, and they were scaffolded using the popular Create React App tool. The tool provides a specific tooling set for applications, including Webpack and others. We have chosen this as it's a proven and stable environment for React applications.

On top of the original scaffolding, we have added some additional files and tooling, and changed some of the default scripts in package-json as to match the ones used by the rest of the GobstonesWeb2 projects. So you can expect gobstones-scripts to be present in this projects also.

Common package.json organization

As we stated, package.json is one of the most important files in any project, as it contains the information of the project (name, version, author, etc.) and also contains the scripts section, which contains common tasks that can be executed to achieve certain goals. In our project we attempt to maintain a common set of script actions.

The first one you will find is the prepare script. This script is executed as a hook by npm when you install all dependencies of the project (e.g. when running npm install for the first time), and we use it to install and initialize Husky at the project's root. You should not run this script manually.

The other two scripts are start and gbs. The gbs script gives special access to the underlying gobstones-script CLI application, even if you didn't install it globally. You can run the gbs task run executing

npm run gbs

This is equivalent to run the global gobstones-scripts command, as long as the local version and global version are the same. You may call gobstones-scripts sub-commands, such as eject or update by simply appending the command at the end. e.g.:

npm run gbs update -i github

The start command is equivalent to running the npm run gbs run command, that is, it runs a task through gobstones-scripts, through the declared nps configuration. But start has the benefit of being a special task for node, so you can execute this command without having to do npm run <script-name> like for other scripts, you can simply do

npm start

This will run the default script on the nps configuration, which most of the time will be abstracted away through gobstones-scripts. By default it prints a list of all the available tasks.

The usual list of tasksthat we provide in any project are:

  • help: Shows a list of all possible commands that can be executed in the project.
  • dev: Execute the current project in development mode. In libraries and CLI libraries, this implies executing the code in src/index.ts, in React libraries corresponds to running StoryBook in watch mode, and in applications it corresponds to executing the application in development mode.
  • build: It generates a distributable file, usually in the dist folder. These are the files that other applications will use when importing the library, or that will be hosting by a server to use the application.
  • test: Run all tests in the project.
  • doc: Generate the project's documentation, usually at a folder named docs.
  • doc.serve: Generate the project's documentation, and then serve the generated folder in a local server.
  • lint: Run the linting process in all files, reporting styling and convention errors.
  • lint.fix: Run the linting process in all files with the auto-fix feature as to correct automatically correctable errors.
  • prettify: Fix the styling of all files in the project that can be solved automatically.

Additional tasks may be present depending on the project itself. You can execute any task by simply running the npm start command followed by the task name.

npm start <task>
On this page: