@citruslime/create-boilerplate 0.1.2 → 0.1.3

package/README.md

@@ -1,30 +1,25 @@
-# Citrus-Lime UI Library Boilerplate Creation
+# Citrus-Lime UI Library Create Boilerplate Script
+
+A create package for initialising Citrus-Lime web apps.
 
 ![version](https://img.shields.io/npm/v/@citruslime/create-boilerplate/latest)
 ![version next](https://img.shields.io/npm/v/@citruslime/create-boilerplate/next)
-![license](https://img.shields.io/npm/l/@citruslime/create-boilerplate)
 
 - ⚡ [NPM Package](https://www.npmjs.com/package/@citruslime/create-boilerplate)
 - 📖 [Documentation & API](https://uilibrary.citruslime.com)
 - 📌 [Citrus-Lime Ltd](https://www.citruslime.com)
 
-## Running the script
 
-⚠️ All of the parameters listed below are required.
+`npm init @citruslime/boilerplate TargetDirectory`
+
+or
+
+`yarn create @citruslime/boilerplate TargetDirectory`
 
-#### Script signature
-```yarn create @citruslime/boilerplate ScriptTarget PackageName FrontEndPortNumber BackendPortNumber AutoRun```
+- **TargetDirectory**
+  - A relative folder path for the script to create the boilerplate app
+  - *Optional* - will be prompted for, if not provided
 
-- **ScriptTarget**
-  - _A relative folder path for the script to create the boilerplate app_
-- **PackageName**
-  - _Using a lower-kebab-cased naming convention_
-- **FrontEndPortNumber**
-  - _The port in which the vite app will run_
-- **BackendPortNumber**
-  - _The port in which the API project which drives the front-end api will run_
-- **AutoRun**
-  - `true|false` _Run the app immediately after creating it_
+e.g.
 
-#### Example Script Execution
-```yarn create @citruslime/boilerplate ./ui/customer app-customer-ui 3001 44531 true```
+`yarn create @citruslime/boilerplate ./ui/customer`

package/hooks/common.sh

@@ -0,0 +1,7 @@
+command_exists () {
+  command -v "$1" >/dev/null 2>&1
+}
+
+if command_exists winpty && test -t 1; then
+  exec < /dev/tty
+fi

package/hooks/post-checkout

@@ -0,0 +1,11 @@
+#!/bin/sh
+. "$(dirname "$0")/_/husky.sh"
+. "$(dirname "$0")/common.sh"
+
+yarn_directory="$APPDATA\npm\node_modules\yarn\bin"
+
+if ! command -v "$yarn_directory\yarn" -v; then
+    npm install --global yarn
+fi
+
+"$yarn_directory\yarn" install -W

package/hooks/post-merge

@@ -0,0 +1,11 @@
+#!/bin/sh
+. "$(dirname "$0")/_/husky.sh"
+. "$(dirname "$0")/common.sh"
+
+yarn_directory="$APPDATA\npm\node_modules\yarn\bin"
+
+if ! command -v "$yarn_directory\yarn" -v; then
+    npm install --global yarn
+fi
+
+"$yarn_directory\yarn" install -W

package/hooks/pre-commit

@@ -0,0 +1,11 @@
+#!/bin/sh
+. "$(dirname "$0")/_/husky.sh"
+. "$(dirname "$0")/common.sh"
+
+yarn_directory="$APPDATA\npm\node_modules\yarn\bin"
+
+if ! command -v "$yarn_directory\yarn" -v; then
+    npm install --global yarn
+fi
+
+"$yarn_directory\yarn" pre-commit-lint

package/main.mjs

@@ -0,0 +1,395 @@
+#!/usr/bin/env node
+
+import { execSync } from 'child_process';
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+import { lightBlue, green, red } from 'kolorist';
+import parseArgs from 'minimist';
+import prompts from 'prompts';
+
+const argv = parseArgs(process.argv.slice(2));
+const cwd = process.cwd();
+const codeDir = fileURLToPath(dirname(import.meta.url));
+
+const placeholdersToReplace = {
+    /* eslint-disable @typescript-eslint/naming-convention */
+    '[[PACKAGE_NAME]]': '',
+    '[[REPOSITORY_ROOT]]': '',
+    '[[HUSKY_DIR]]': '',
+    '[[BACKEND_PORT]]': 0,
+    '[[FRONTEND_PORT]]': 0,
+    '\n        // eslint-disable-next-line array-bracket-spacing': ''
+    /* eslint-enable @typescript-eslint/naming-convention */
+};
+
+const filesToRename = {
+    /* eslint-disable @typescript-eslint/naming-convention */
+    _gitignore: '.gitignore',
+    _editorconfig: '.editorconfig',
+    _eslintignore: '.eslintignore',
+    '_eslintrc.js': '.eslintrc.js',
+    '_lintstagedrc.json': '.lintstagedrc.json',
+    _stylelintignore: '.stylelintignore',
+    '_stylelintrc.js': '.stylelintrc.js',
+    'template.code-workspace': 'citrus-lime.code-workspace'
+    /* eslint-enable @typescript-eslint/naming-convention */
+};
+
+const dependenciesToInstall = [
+    {
+        name: '@citruslime/ui'
+    },
+    {
+        name: '@vueuse/core'
+    },
+    {
+        name: 'flatpickr'
+    },
+    {
+        name: 'pinia'
+    },
+    {
+        name: 'pinia-plugin-persistedstate'
+    },
+    {
+        name: 'vue'
+    },
+    {
+        name: 'vue-i18n'
+    },
+    {
+        name: 'vue-router'
+    },
+    {
+        name: '@citruslime/config',
+        dev: true
+    },
+    {
+        name: '@citruslime/theme',
+        dev: true
+    },
+    {
+        name: '@types/node',
+        dev: true
+    },
+    {
+        name: '@vitejs/plugin-vue',
+        dev: true
+    },
+    {
+        name: '@iconify/vue',
+        dev: true
+    },
+    {
+        name: 'husky',
+        dev: true
+    },
+    {
+        name: 'lint-staged',
+        dev: true
+    },
+    {
+        name: 'postcss',
+        dev: true
+    },
+    {
+        name: 'typescript',
+        dev: true
+    },
+    {
+        name: 'unplugin-vue-components',
+        dev: true
+    },
+    {
+        name: 'vite',
+        dev: true
+    },
+    {
+        name: 'vite-plugin-mkcert',
+        dev: true
+    },
+    {
+        name: 'vite-plugin-pages',
+        dev: true
+    },
+    {
+        name: 'vue-tsc',
+        dev: true
+    }
+];
+
+/**
+ * Initialise the new package.
+ */
+async function init () {
+    let packageDir = argv._[0];
+
+    const {
+        packageName,
+        empty,
+        packageManager,
+        rootDir,
+        frontendPort,
+        backendPort
+    } = await prompts([
+        {
+            type: 'text',
+            name: 'packageName',
+            message: 'Enter a package name:',
+            validate: (value) => /^(?:@[a-z0-9-*~][a-z0-9-*._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/.test(value)
+        },
+        {
+            type: packageDir ? null : 'text',
+            name: 'packageDir',
+            message: 'Enter a directory for the package:',
+            onState: (state) => packageDir = state.value
+        },
+        {
+            type: () => !existsSync(packageDir) || readdirSync(packageDir).length === 0 ? null : 'confirm',
+            name: 'empty',
+            message: () => `${packageDir === '.' ? 'Current directory' : `Target directory "${packageDir}"`} is not empty. Remove existing files and continue?`
+        },
+        {
+            type (_, { empty }) {
+                if (empty === false) {
+                    cancel();
+                }
+
+                return null;
+            },
+            name: 'emptyConfirmation'
+        },
+        {
+            type: 'select',
+            name: 'packageManager',
+            message: 'Select a package manager:',
+            choices: [
+                {
+                    title: 'yarn',
+                    value: 'yarn'
+                },
+                {
+                    title: 'npm',
+                    value: 'npm'
+                }
+            ],
+            initial: 0
+        },
+        {
+            type: 'text',
+            name: 'rootDir',
+            message: 'Enter the relative path to the root of the repository:',
+            validate: (value) => value && value?.trim() !== ''
+        },
+        {
+            type: 'number',
+            name: 'frontendPort',
+            message: 'Enter the port for the dev server to run on:'
+        },
+        {
+            type: 'text',
+            name: 'backendPort',
+            message: 'Enter the port that the backend server runs on:'
+        }
+    ], {
+        onCancel: () => cancel()
+    });
+
+    print(lightBlue('Initialising package...'), true);
+
+    packageDir = packageDir.toString();
+
+    setReplacements(packageName, rootDir, frontendPort, backendPort);
+    prepareDir(join(cwd, packageDir), empty);
+    copyTemplate(packageDir);
+
+    process.chdir(packageDir);
+    installDependencies(packageManager);
+
+    print(lightBlue('Creating hooks...'), true);
+    copyHooks(packageDir, rootDir);
+
+    print(green(`Package ${packageName} has been successfully initialised in ${packageDir}.`), true);
+}
+
+/**
+ * Set the dynamic values for the file renaming and placeholder replacements.
+ *
+ * @param {string} packageName The name of the package being created.
+ * @param {string} rootDir The relative path of the root of the repository.
+ * @param {number} frontendPort The port that the frontend dev server will run on.
+ * @param {number} backendPort The port that the backend server runs on.
+ */
+function setReplacements (packageName, rootDir, frontendPort, backendPort) {
+    filesToRename['template.code-workspace'] = `${packageName}.code-workspace`;
+
+    placeholdersToReplace['[[PACKAGE_NAME]]'] = packageName;
+    placeholdersToReplace['[[REPOSITORY_ROOT]]'] = rootDir;
+    placeholdersToReplace['[[HUSKY_DIR]]'] = join(rootDir, '.husky').replace('\\', '/');
+    placeholdersToReplace['[[FRONTEND_PORT]]'] = frontendPort;
+    placeholdersToReplace['[[BACKEND_PORT]]'] = backendPort;
+}
+
+/**
+ * Prepares the directory for the new package to be created in.
+ *
+ * @param {string} path The path of the directory to be prepared.
+ * @param {boolean} empty If the current contents needs to be emptied.
+ */
+function prepareDir (path, empty) {
+    if (empty) {
+        const options = {
+            recursive: true,
+            force: true
+        };
+
+        print(lightBlue('Emptying directory...'), true);
+
+        forEachInDir(path, (item) => rmSync(join(path, item), options));
+    }
+    else if (!existsSync(path)) {
+        print(lightBlue('Creating directory...'), true);
+
+        mkdirSync(path);
+    }
+}
+
+/**
+ * Copies the template directory into the new package directory.
+ *
+ * @param {string} packageDir The directory of the new package.
+ */
+function copyTemplate (packageDir) {
+    const templateDir = join(codeDir, 'template');
+
+    forEachInDir(templateDir, (item) => copy(templateDir, packageDir, item));
+}
+
+/**
+ * Copies the hooks directory into the husky directory for the repository.
+ *
+ * @param {string} packageDir The directory of the new package.
+ * @param {string} rootDir The relative path from the package directory to the root of the repository.
+ */
+function copyHooks (packageDir, rootDir) {
+    const hooksDir = join(codeDir, 'hooks');
+    const huskyDir = join(cwd, packageDir, rootDir, '.husky');
+
+    forEachInDir(hooksDir, (item) => copy(hooksDir, huskyDir, item));
+}
+
+/**
+ * Copies a file or directory from one location to another.
+ *
+ * @param {string} source The path of the item to copy.
+ * @param {string} destination The path of the new item.
+ * @param {string} item The item to copy.
+ */
+function copy (source, destination, item) {
+    const sourceItem = join(source, item);
+    const info = statSync(sourceItem);
+
+    if (info.isDirectory()) {
+        const destinationDir = join(destination, item);
+
+        mkdirSync(destinationDir, { recursive: true });
+
+        forEachInDir(sourceItem, (item) => copy(sourceItem, destinationDir, item));
+    }
+    else {
+        const destinationFile = filesToRename[item] ? join(destination, filesToRename[item]) : join(destination, item);
+
+        if (existsSync(destinationFile)) {
+            print(lightBlue(`Skipping ${item}...`), true);
+        }
+        else {
+            const options = {
+                encoding: 'utf-8'
+            };
+
+            print(lightBlue(`Copying ${item}...`), true);
+
+            let contents = readFileSync(sourceItem, options);
+
+            for (const [
+                key,
+                value
+            ] of Object.entries(placeholdersToReplace)) {
+                contents = contents.replace(key, value);
+            }
+
+            writeFileSync(destinationFile, contents, options);
+        }
+    }
+}
+
+/**
+ * Installs the required dependencies for the template.
+ *
+ * @param {string} packageManager The package manager to use.
+ */
+function installDependencies (packageManager) {
+    const prefix = `${packageManager} ${packageManager === 'yarn' ? 'add' : 'install'}`;
+
+    print(lightBlue('Installing dev dependencies...'), true);
+
+    let devDependencies = '';
+    for (const dependency of dependenciesToInstall.filter(d => d.dev)) {
+        devDependencies += `${dependency.name}${dependency.next ? '@next' : '@latest'} `;
+    }
+
+    print(lightBlue('Installing dependencies...'), true);
+
+    let dependencies = '';
+    for (const dependency of dependenciesToInstall.filter(d => !d.dev)) {
+        dependencies += `${dependency.name}${dependency.next ? '@next' : '@latest'} `;
+    }
+
+    execSync(`${prefix} -D ${devDependencies}`);
+    execSync(`${prefix} ${dependencies}`);
+}
+
+/**
+ * Calls the callback for each item in a directory.
+ *
+ * @param {string} dir The directory to loop-through the contents of.
+ * @param {function(string): void} callback The callback to provide with each item.
+ */
+function forEachInDir (dir, callback) {
+    const items = readdirSync(dir);
+
+    for (const item of items) {
+        callback(item);
+    }
+}
+
+/**
+ * Throws an error to indicate that the current operation has been cancelled.
+ */
+function cancel () {
+    throw new Error('Operation was cancelled.');
+}
+
+/**
+ * Prints a message to the console.
+ *
+ * @param {string} message The message to display.
+ * @param {boolean} clearPrevious Whether to clear the previous line before displaying the new one.
+ */
+function print (message, clearPrevious = false) {
+    if (clearPrevious) {
+        process.stdout.clearLine();
+        process.stdout.cursorTo(0);
+    }
+
+    process.stdout.write(message);
+}
+
+try {
+    await init();
+}
+catch (e) {
+    print(`\n${red(e.message)}`);
+}

package/package.json

@@ -1,34 +1,33 @@
 {
     "name": "@citruslime/create-boilerplate",
-    "version": "0.1.2",
+    "version": "0.1.3",
     "author": {
         "name": "Citrus-Lime Ltd",
         "url": "https://citruslime.com"
     },
     "license": "MIT",
     "homepage": "https://uilibrary.citruslime.com/",
-    "repository": {
-        "url": "https://dev.azure.com/citruslime/FutureEcommerce/_git/CitrusLime.VueUiLibrary?version=GBrelease"
-    },
     "publishConfig": {
         "access": "public"
     },
     "files": [
-        "index.js",
-        "boilerplate-*"
+        "main.mjs",
+        "template",
+        "hooks"
     ],
-    "main": "index.js",
+    "main": "main.mjs",
     "bin": {
-        "create-boilerplate": "index.js",
-        "cva": "index.js"
+        "create-boilerplate": "main.mjs"
     },
     "engines": {
-        "node": ">=12.0.0"
+        "node": ">=14.0.0"
     },
     "dependencies": {
-        "core-js": "3.15.2",
-        "kolorist": "^1.5.0",
+        "kolorist": "^1.5.1",
         "minimist": "^1.2.5",
-        "prompts": "^2.4.1"
+        "prompts": "^2.4.2"
+    },
+    "devDependencies": {
+        "@types/prompts": "^2.0.14"
     }
 }

package/{boilerplate-app → template}/.vscode/extensions.json

@@ -4,11 +4,10 @@
         "dbaeumer.vscode-eslint",
         "stylelint.vscode-stylelint",
         "bradlc.vscode-tailwindcss",
-        "adrianwilczynski.csharp-to-typescript",
         "eamodio.gitlens",
-        "ms-vsliveshare.vsliveshare",
         "christian-kohler.npm-intellisense",
-        "kevinmcgowan.typescriptimport",
-        "editorconfig.editorconfig"
+        "editorconfig.editorconfig",
+        "cpylua.language-postcss",
+        "antfu.iconify"
     ]
 }

package/{boilerplate-app → template}/.vscode/settings.json

@@ -5,6 +5,9 @@
     "css.validate": false,
     "diffEditor.ignoreTrimWhitespace": false,
     "editor.codeActionsOnSave": {
+        "source.fixAll": true,
+        "source.fixAll.eslint": true,
+        "source.fixAll.stylelint": true,
         "source.organizeImports": false
     },
     "editor.defaultFormatter": "dbaeumer.vscode-eslint",
@@ -20,22 +23,15 @@
     ],
     "files.encoding": "utf8",
     "files.eol": "\n",
-    "files.exclude": {
-        "node_modules": true
-    },
     "files.trimTrailingWhitespace": true,
-    "git.autofetch": true,
-    "git.autofetchPeriod": 60,
-    "git.enableSmartCommit": true,
-    "git.pruneOnFetch": true,
     "npm-intellisense.scanDevDependencies": true,
     "npm-intellisense.showBuildInLibs": true,
+    "stylelint.validate": [
+        "css",
+        "postcss",
+        "vue"
+    ],
     "tailwindCSS.includeLanguages": {
         "vue": "html"
-    },
-    "typescript.preferences.quoteStyle": "single",
-    "typescript.tsdk": "node_modules\\typescript\\lib",
-    "typescript.updateImportsOnFileMove.enabled": "always",
-    "volar.tsPlugin": true,
-    "volar.tsPluginStatus": false
+    }
 }

package/{boilerplate-app/.vscode/boilerplate-app.code-workspace → template/.vscode/template.code-workspace}

@@ -6,7 +6,7 @@
         },
         {
             "name": "Hooks",
-            "path": "../../.husky"
+            "path": "../[[HUSKY_DIR]]"
         }
     ],
     "settings": {
@@ -16,6 +16,9 @@
         "css.validate": false,
         "diffEditor.ignoreTrimWhitespace": false,
         "editor.codeActionsOnSave": {
+            "source.fixAll": true,
+            "source.fixAll.eslint": true,
+            "source.fixAll.stylelint": true,
             "source.organizeImports": false
         },
         "editor.defaultFormatter": "dbaeumer.vscode-eslint",
@@ -31,24 +34,17 @@
         ],
         "files.encoding": "utf8",
         "files.eol": "\n",
-        "files.exclude": {
-            "node_modules": true
-        },
         "files.trimTrailingWhitespace": true,
-        "git.autofetch": true,
-        "git.autofetchPeriod": 60,
-        "git.enableSmartCommit": true,
-        "git.pruneOnFetch": true,
         "npm-intellisense.scanDevDependencies": true,
         "npm-intellisense.showBuildInLibs": true,
+        "stylelint.validate": [
+            "css",
+            "postcss",
+            "vue"
+        ],
         "tailwindCSS.includeLanguages": {
             "vue": "html"
-        },
-        "typescript.preferences.quoteStyle": "single",
-        "typescript.tsdk": "node_modules\\typescript\\lib",
-        "typescript.updateImportsOnFileMove.enabled": "always",
-        "volar.tsPlugin": true,
-        "volar.tsPluginStatus": false
+        }
     },
     "extensions": {
         "recommendations": [
@@ -56,12 +52,11 @@
             "dbaeumer.vscode-eslint",
             "stylelint.vscode-stylelint",
             "bradlc.vscode-tailwindcss",
-            "adrianwilczynski.csharp-to-typescript",
             "eamodio.gitlens",
-            "ms-vsliveshare.vsliveshare",
             "christian-kohler.npm-intellisense",
-            "kevinmcgowan.typescriptimport",
-            "editorconfig.editorconfig"
+            "editorconfig.editorconfig",
+            "cpylua.language-postcss",
+            "antfu.iconify"
         ]
     }
 }

package/template/README.md

@@ -0,0 +1,11 @@
+# Citrus-Lime Boilerplate App
+
+This boilerplate should provide a good basis for creating a new Citrus-Lime web app.
+
+It makes use of the various @citruslime packages, as well as the current standards for a Vue 3 + TypeScript app and various helpful Vite plugins to make development easier.
+
+Linting is provided by default by a combination of ESLint and StyleLint.
+
+## Areas of Consideration
+
+Example code is provided in the state and views folders. It should be deleted or replaced, once development is started.

package/template/_eslintrc.js

@@ -0,0 +1,3 @@
+module.exports = {
+    extends: [ require.resolve('@citruslime/config/eslint') ]
+};

package/{boilerplate-app → template}/_gitignore

@@ -3,3 +3,4 @@ node_modules
 dist
 dist-ssr
 *.local
+*.log

package/{boilerplate-app → template}/_lintstagedrc.json

@@ -2,7 +2,7 @@
     "./**/*.+(js|ts|vue)": [
         "eslint --fix"
     ],
-    "./**/*.css": [
+    "./**/*.(css|vue)": [
         "stylelint --fix"
     ]
 }