File structure

Example

kladovka
├───.vscode
|   └───settings.json
|
├───assets
|   └───user_uploaded_file.jpg
|
├───e2e
│   ├───test
│   │   ├───pageobjects
│   │   |   └───page.js
│   │   ├───main.e2e.js
│   |   └───.eslintrc.json
│   └───wdio.conf.js
|
├───frontend
│   ├───dist
│   |   ├───bundle.js
│   |   ├───index.html
│   |   └───style.css
│   ├───static
│   |   ├───logo.png
│   |   └───favicon.ico
│   ├───src
│   |   ├───templates
│   |   |   ├───main.ejs
│   |   |   └───another.ejs
│   |   ├───components
│   |   |   ├───kl-app.vue
│   |   |   └───kl-app.js
│   |   ├───index.html
│   |   ├───style.css
│   |   └───.eslintrc.json
│   ├───doc
│   └───webpack.config.js
|
├───backend
|   ├───migrations
|   |   └───001_init_db.js
│   ├───src
│   |   └───rest.js
│   └───test
│       └───url.rest
|
├───domain
│   ├───src
│   |   └───db.async.proxy.js
│   └───test
│       ├───db.async.test.js
│       └───.eslintrc.json
|
├───.eslintrc.json
├───.eslintignore
├───.gitignore
├───README.md
└───package.json

Reasoning

sub-projects

Project should be split into modules, or sub-projects. Everything related to the domain layer should go to domain directory, everything related to the server-side should go to backend directory etc. End-to-end tests should be considered as another module as they are not bound to any other particular module; instead, they are for the entire application.

assets is a directory for user-uploaded files and also should be at the top level.

sub-directories

"Normal" directories (like src, lib, test, doc etc) should be in singular form and written exactly as in npm package.json documentation.

"Custom" directories (like pageobjects, components etc) should be more descriptive and in plural form.

Generated files should go to the dist directory.

tests

Test files should go under test directory, and it should be located as a sibling to the src directory. Structure of the test files should mirror structure of the files in src and should be named the same as corresponding src file with a .test suffix.

Example

src
\_ main.js
test
\_ main.test.js

package.json and .vscode

There should be single package.json for a project, as well as single .vscode directory - managing sub-projects is kinda clunky and have issues when we need to edit several sub-projects simultaneously. The workflow is to open root directory in VSCode and work from there.

package.json

License should be MIT. Usage of globally installed packages and utilities is discouraged, all utilities like mocha, eslint etc should be installed locally. Build tasks should be managed in the scripts section, usage of gulp or grunt etc is discouraged (so far everything we need is accomplished by npm without any troubles so introducing additional tools is just unnecessary complication). Only those things that are required at runtime go to the dependencies section, only those things that are required for build go to the devDependencies section, and all the other stuff (including eslint and mocha and everything related to testing) go to the optionalDependencies. That is so that if we just want to build, we should not be stuck dealing with some test-related issues and installations.

.vscode

node_modules and generated (compiled) files (like dist or lib) should be hidden from VSCode for cleaner view on the sources.

Example .vscode/settings.json for javascript project

{
    "markdownlint.config": {
        "MD013": false,
        "MD041": false,
        "MD029": false
    },
    "files.exclude": {
        ".git": true,
        ".vscode/chrome": true,
        "node_modules": true,
        ".vagrant": true,
        "**/dist": true
    }
}

Example .vscode/settings.json for typescript project

{
    "typescript.tsdk": "node_modules/typescript/lib/",
    "markdownlint.config": {
        "MD013": false,
        "MD041": false,
        "MD029": false
    },
    "files.exclude": {
        ".git": true,
        "lib": true,
        "node_modules": true
    },
    "typescript.format.insertSpaceAfterFunctionKeywordForAnonymousFunctions": false
}

.eslintrc.json

Linter to use is ESLint. We were used to work with JSHint, but it had troubles with dealing with some experimental features (async/await in particular), so we switched to ESLint.

There should be an .eslintrc.json in the root of project applying settings which are common for the entire project. All .eslintrc.json files in the sub-directories should have extends option:

    ...
    "extends": "../.eslintrc.json",
    ...

Example of the root .eslintrc.json

{
    "extends": "eslint:recommended",
    "env": {
        "es6": true
    },
    "parserOptions": {
        "ecmaVersion": 8,
        "sourceType": "module"
    },
    "rules": {
        "semi": [
            "warn",
            "always"
        ],
        "no-unused-vars": [
            "warn",
            {
                "vars": "all",
                "args": "none"
            }
        ]
    }
}

Example of the sub-directory .eslintrc.json

{
    "extends": "../.eslintrc.json",
    "env": {
        "node": true
    }
}

.eslintignore

Should be a single file in the root of the project (detailed reasoning).