@contentful/create-contentful-app 0.15.12 → 1.1.0-alpha.10

package/README.md

@@ -1,26 +1,89 @@
+<!-- Don't forget to also update the corresponding README.md of the create-contentful-app package -->
+
 # Create Contentful App
 
-This project makes it easy to bootstrap [Contentful Apps](https://www.contentful.com/developers/docs/extensibility/app-framework/) with [React](https://reactjs.org/) and [Forma 36](https://f36.contentful.com/) (Contentful's design system).
+`create-contentful-app` is a command line interface to easily bootstrap [Contentful Apps](https://www.contentful.com/developers/docs/extensibility/app-framework/).
 
-## Requirements
+# Requirements
 
-- Node.js v14 or v16
-- NPM v6
+- Node.js v14.15 or v16
+- npm v6 or later
 
-# Quick Overview
+# Usage
 
-To start developing your app:
+To start developing your first app, run:
 
+```bash
+npx create-contentful-app my-first-app
 ```
-npx @contentful/create-contentful-app init my-first-app
-cd my-first-app
-npm start
-```
 
-To use your app, you need to create an [app definition](https://www.contentful.com/developers/docs/references/content-management-api/#/reference/app-definitions):
+![Screenshot of `npx create-contentful-app my-app`](./docs/screenshot.png)
+
+## Bootstrap
+
+You can run `create-contentful-app` using one of the following commands:
 
+```bash
+# npx
+npx create-contentful-app <app-name>
+
+# npm
+npm init contentful-app <app-name>
+
+# Yarn
+yarn create contentful-app <app-name>
 ```
-npx @contentful/create-contentful-app create-definition
+
+## CLI Options
+
+### Package Manager
+
+`--npm` or `--yarn`
+
+Use npm or Yarn to manage dependencies. If omitted, defaults to the manager used to run `create-contentful-app`.
+
+Both flags are mutually exclusive.
+
+### Template
+
+Select between predefined and custom templates:
+
+- `-ts, --typescript`: Use TypeScript template (default)
+- `-js, --javascript`: Use JavaScript template
+- `-e, --example <example-name>`: Select a predefined template from https://github.com/contentful/apps/tree/master/examples
+- `-s, --source <url>`: Use a custom template. Format: URL (HTTPS or SSH) or vendor:user/repo (e.g., github:user/repo)
+
+These flags are mutually exclusive. If no flag is provided, the TypeScript template is used.
+
+### Help
+
+`--help`
+
+Shows all available CLI options:
+
 ```
+Usage: npx create-contentful-app [options] [app-name]
+
+Bootstrap your app inside a new folder `my-app`
 
-[Read more](https://www.contentful.com/developers/docs/extensibility/app-framework/create-contentful-app/) and check out the video on how to use the CLI.
+  create-contentful-app my-app
+
+or specify your own template
+
+  create-contentful-app my-app --source "github:user/repo"
+
+Official Contentful templates are hosted at https://github.com/contentful/apps/tree/master/examples.
+
+Arguments:
+  app-name                      app name
+
+Options:
+  --npm                         use npm
+  --yarn                        use Yarn
+  -js, --javascript             use default JavaScript template
+  -ts, --typescript             use default TypeScript template
+  -e, --example <example-name>  bootstrap an example app from https://github.com/contentful/apps/tree/master/examples
+  -s, --source <url>            provide a template by its source repository.
+                                format: URL (HTTPS or SSH) or vendor:user/repo (e.g., github:user/repo)
+  -h, --help                    shows all available CLI options
+```

package/lib/index.js

@@ -1,133 +1,131 @@
 #!/usr/bin/env node
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = require("fs");
+const path_1 = require("path");
+const os_1 = require("os");
+const validate_npm_package_name_1 = __importDefault(require("validate-npm-package-name"));
+const commander_1 = require("commander");
+const inquirer_1 = __importDefault(require("inquirer"));
+const tildify_1 = __importDefault(require("tildify"));
+const template_1 = require("./template");
+const utils_1 = require("./utils");
+const logger_1 = require("./logger");
+const DEFAULT_APP_NAME = 'contentful-app';
+function successMessage(folder) {
+    console.log(`
+${(0, logger_1.success)('Success!')} Created a new Contentful app in ${(0, logger_1.highlight)((0, tildify_1.default)(folder))}.
 
-/* eslint-disable no-console, no-process-exit */
-
-const chalk = require('chalk');
-const spawn = require('cross-spawn');
-const path = require('path');
-const tildify = require('tildify');
-const { createAppDefinition } = require('@contentful/app-scripts');
-const packageJson = require('../package.json');
-
-const command = process.argv[2];
-const appFolder = process.argv[3];
-
-const localCommand = '@contentful/create-contentful-app';
-const mainCommand = `npx ${localCommand}`;
-
-function getTemplate() {
-  const templatePkg = '@contentful/cra-template-create-contentful-app';
-
-  if (!process.env.USE_LINKED_TEMPLATE) {
-    const templateVersion =
-      packageJson.dependencies['@contentful/cra-template-create-contentful-app'].slice(1);
-    return `${templatePkg}@${templateVersion}`;
-  }
-
-  const linkedTemplatePath = path.relative(
-    process.cwd(),
-    path.dirname(require.resolve(templatePkg))
-  );
-
-  console.log();
-  console.log(chalk.dim('> Using linked template at %s'), chalk.blueBright(linkedTemplatePath));
-  console.log();
-
-  return `file:${linkedTemplatePath}`;
-}
-
-function onSuccess(folder) {
-  console.log(`
-${chalk.cyan('Success!')} Created a new Contentful app in ${chalk.bold(
-    tildify(path.resolve(process.cwd(), folder))
-  )}.
-
-We suggest that you begin by running:
+Now kick it off by running
 
-    ${chalk.cyan(`cd ${folder}`)}
-    ${chalk.cyan(`${mainCommand} create-definition`)}
+    ${(0, logger_1.code)(`cd ${(0, tildify_1.default)(folder)}`)}
+    ${(0, logger_1.code)(`npm start`)}
   `);
-
-  process.exit();
 }
-
-function initProject() {
-  try {
-    if (!appFolder) {
-      console.log();
-      console.log(
-        `Please provide a name for your app, e.g. ${chalk.cyan(`\`${mainCommand} init my-app\``)}.`
-      );
-      console.log();
-      process.exit(1);
-    }
-
-    const initCommand = 'node';
-    const createReactApp = require.resolve('create-react-app');
-    const template = getTemplate();
-
-    const args = [createReactApp, appFolder, '--template', template, '--use-npm'];
-
-    console.log(
-      `Creating a Contentful app in ${chalk.bold(tildify(path.resolve(process.cwd(), appFolder)))}.`
-    );
-
-    const appCreateProcess = spawn(initCommand, args, { stdio: 'inherit' });
-    appCreateProcess.on('exit', (exitCode) => {
-      if (exitCode === 0) {
-        onSuccess(appFolder);
-      } else {
-        process.exit(exitCode);
-      }
+function updatePackageName(appFolder) {
+    const packageJsonPath = (0, path_1.resolve)(appFolder, 'package.json');
+    const packageJson = JSON.parse((0, fs_1.readFileSync)(packageJsonPath, { encoding: 'utf-8' }));
+    packageJson.name = (0, path_1.basename)(appFolder);
+    (0, fs_1.writeFileSync)(packageJsonPath, JSON.stringify(packageJson, null, 2) + os_1.EOL);
+}
+function promptAppName() {
+    return __awaiter(this, void 0, void 0, function* () {
+        return yield inquirer_1.default.prompt([
+            {
+                name: 'name',
+                message: 'App name',
+                default: DEFAULT_APP_NAME,
+            },
+        ]);
     });
-  } catch (err) {
-    console.log(`${chalk.red('Error:')} Failed to create ${appFolder}:
-
-      ${err}
-      `);
-    process.exit(1);
-  }
 }
-
-(async function main() {
-  function printHelpText() {
-    console.log(`
-${chalk.bold(localCommand)}
-
-${chalk.dim('Available commands:')}
-
-${chalk.cyan(`$ ${mainCommand} init app-name`)}
-
-  Bootstraps your app inside a new folder "app-name".
-
-${chalk.cyan(`$ ${mainCommand} create-definition`)}
-
-  Creates an app definition for your app in a Contentful
-  organization of your choice.
-  `);
-  }
-
-  switch (command) {
-    case 'init':
-      initProject();
-      break;
-
-    case 'create-definition':
-      await createAppDefinition.interactive();
-      break;
-
-    case 'help':
-      printHelpText();
-      break;
-
-    case undefined:
-      printHelpText();
-      break;
-
-    default:
-      console.log();
-      console.log(`${chalk.red('Error:')} Unknown command.`);
-      printHelpText();
-      process.exit(1);
-  }
+/**
+ * Validates the user input and ensures it can be used as app name. If no app name is provided, shows a prompt.
+ *
+ * @param appName App name entered by the user
+ * @returns Valid app name
+ */
+function validateAppName(appName) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (appName === 'create-definition') {
+            throw new Error(`The ${(0, logger_1.code)('create-definition')} command has been removed from ${(0, logger_1.code)('create-contentful-app')}.\nTo create a new app definition first run ${(0, logger_1.code)('npx create-contentful-app')} and then ${(0, logger_1.code)('npm run create-app-definition')} within the new folder.`);
+        }
+        if (appName === 'init') {
+            (0, logger_1.warn)(`The ${(0, logger_1.code)('init')} command has been removed from ${(0, logger_1.code)('create-contentful-app')}. You can now create new apps running ${(0, logger_1.code)('npx create-contentful-app')} directly.`);
+            appName = '';
+        }
+        if (!appName) {
+            const prompt = yield promptAppName();
+            appName = prompt.name;
+        }
+        if (!(0, validate_npm_package_name_1.default)(appName).validForNewPackages) {
+            throw new Error(`Cannot create an app named "${appName}". Please choose a different name for your app.`);
+        }
+        return appName;
+    });
+}
+function initProject(appName, options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const normalizedOptions = (0, utils_1.normalizeOptions)(options);
+        try {
+            appName = yield validateAppName(appName);
+            const fullAppFolder = (0, path_1.resolve)(process.cwd(), appName);
+            console.log(`Creating a Contentful app in ${(0, logger_1.highlight)((0, tildify_1.default)(fullAppFolder))}.`);
+            yield (0, template_1.cloneTemplateIn)(fullAppFolder, normalizedOptions);
+            updatePackageName(fullAppFolder);
+            if (normalizedOptions.yarn || (0, utils_1.detectManager)() === 'yarn') {
+                yield (0, utils_1.exec)('yarn', [], { cwd: fullAppFolder });
+            }
+            else {
+                yield (0, utils_1.exec)('npm', ['install', '--no-audit', '--no-fund'], { cwd: fullAppFolder });
+            }
+            successMessage(fullAppFolder);
+        }
+        catch (err) {
+            (0, logger_1.error)(`Failed to create ${appName}`, String(err));
+            process.exit(1);
+        }
+    });
+}
+(function main() {
+    return __awaiter(this, void 0, void 0, function* () {
+        commander_1.program
+            .name(`npx ${(0, logger_1.code)('create-contentful-app')}`)
+            .helpOption(true, 'shows all available CLI options')
+            .description([
+            'Bootstrap your app inside a new folder `my-app`',
+            '',
+            (0, logger_1.code)('  create-contentful-app my-app'),
+            '',
+            'or specify your own template',
+            '',
+            (0, logger_1.code)('  create-contentful-app my-app --source "github:user/repo"'),
+            '',
+            `Official Contentful templates are hosted at ${(0, logger_1.highlight)('https://github.com/contentful/apps/tree/master/examples')}.`,
+        ].join('\n'))
+            .argument('[app-name]', 'app name')
+            .option('--npm', 'use npm')
+            .option('--yarn', 'use Yarn')
+            .option('-ts, --typescript', 'use TypeScript template (default)')
+            .option('-js, --javascript', 'use JavaScript template')
+            .option('-e, --example <example-name>', 'bootstrap an example app from https://github.com/contentful/apps/tree/master/examples')
+            .option('-s, --source <url>', [
+            `provide a template by its source repository.`,
+            `format: URL (HTTPS or SSH) or ${(0, logger_1.code)('vendor:user/repo')} (e.g., ${(0, logger_1.code)('github:user/repo')})`,
+        ].join('\n'))
+            .action(initProject);
+        yield commander_1.program.parseAsync();
+    });
 })();

package/lib/logger.js

@@ -0,0 +1,34 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.code = exports.success = exports.choice = exports.highlight = exports.error = exports.warn = void 0;
+const chalk_1 = __importDefault(require("chalk"));
+function warn(message) {
+    console.log(`${chalk_1.default.yellow('Warning:')} ${message}`);
+}
+exports.warn = warn;
+function error(message, error) {
+    console.log(`${chalk_1.default.red('Error:')} ${message}
+
+  ${error.startsWith('Error: ') ? error.substring(7) : error}
+`);
+}
+exports.error = error;
+function highlight(str) {
+    return chalk_1.default.bold(str);
+}
+exports.highlight = highlight;
+function choice(str) {
+    return chalk_1.default.cyan(str);
+}
+exports.choice = choice;
+function success(str) {
+    return chalk_1.default.greenBright(str);
+}
+exports.success = success;
+function code(str) {
+    return chalk_1.default.bold(str);
+}
+exports.code = code;

package/lib/template.js

@@ -0,0 +1,95 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cloneTemplateIn = void 0;
+const path_1 = require("path");
+const fs_1 = require("fs");
+const degit_1 = __importDefault(require("degit"));
+const rimraf_1 = __importDefault(require("rimraf"));
+const types_1 = require("./types");
+const logger_1 = require("./logger");
+const utils_1 = require("./utils");
+const EXAMPLES_PATH = 'contentful/apps/examples/';
+function isContentfulTemplate(url) {
+    return Object.values(types_1.ContentfulExample).some(t => url.includes(EXAMPLES_PATH + t));
+}
+function makeContentfulExampleSource(options) {
+    if (options.example) {
+        return EXAMPLES_PATH + options.example;
+    }
+    if (options.javascript) {
+        return EXAMPLES_PATH + types_1.ContentfulExample.Javascript;
+    }
+    return EXAMPLES_PATH + types_1.ContentfulExample.Typescript;
+}
+function getTemplateSource(options) {
+    var _a;
+    const source = (_a = options.source) !== null && _a !== void 0 ? _a : makeContentfulExampleSource(options);
+    if (options.source && !isContentfulTemplate(source)) {
+        (0, logger_1.warn)(`Template at ${(0, logger_1.highlight)(source)} is not an official Contentful app template!`);
+    }
+    return source;
+}
+function clone(source, destination) {
+    var _a;
+    return __awaiter(this, void 0, void 0, function* () {
+        const d = (0, degit_1.default)(source, { mode: 'tar', cache: false });
+        try {
+            yield d.clone(destination);
+        }
+        catch (e) {
+            let message = (_a = e.message) !== null && _a !== void 0 ? _a : 'Unknown error';
+            if (e.code === 'DEST_NOT_EMPTY') {
+                message = 'Destination directory is not empty.';
+            }
+            throw new Error(message);
+        }
+    });
+}
+function validate(destination) {
+    const packageJSONLocation = `${destination}/package.json`;
+    if (!(0, fs_1.existsSync)(packageJSONLocation)) {
+        throw new Error(`Invalid template: missing "${packageJSONLocation}".`);
+    }
+    let packageJSON;
+    try {
+        packageJSON = JSON.parse((0, fs_1.readFileSync)(packageJSONLocation, 'utf-8'));
+    }
+    catch (e) {
+        throw new Error(`Invalid template: invalid "${packageJSONLocation}".`);
+    }
+    if (!Object.keys(packageJSON.dependencies).includes('@contentful/app-sdk')) {
+        throw new Error(`Invalid template: missing "@contentful/app-sdk" in "${packageJSONLocation}".`);
+    }
+}
+function cleanUp(destination) {
+    (0, utils_1.rmIfExists)((0, path_1.resolve)(destination, 'package-lock.json'));
+    (0, utils_1.rmIfExists)((0, path_1.resolve)(destination, 'yarn.lock'));
+}
+function cloneTemplateIn(destination, options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const source = getTemplateSource(options);
+        yield clone(source, destination);
+        try {
+            validate(destination);
+        }
+        catch (e) {
+            // cleanup in case of invalid example
+            rimraf_1.default.sync(destination);
+            throw e;
+        }
+        cleanUp(destination);
+    });
+}
+exports.cloneTemplateIn = cloneTemplateIn;

package/lib/types.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContentfulExample = void 0;
+exports.ContentfulExample = {
+    Javascript: 'javascript',
+    Typescript: 'typescript'
+};

package/lib/utils.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeOptions = exports.detectManager = exports.rmIfExists = exports.exec = void 0;
+const child_process_1 = require("child_process");
+const fs_1 = require("fs");
+const path_1 = require("path");
+const logger_1 = require("./logger");
+const MUTUALLY_EXCLUSIVE_OPTIONS = ['source', 'example', 'javascript', 'typescript'];
+function exec(command, args, options) {
+    return new Promise((resolve, reject) => {
+        const process = (0, child_process_1.spawn)(command, args, Object.assign({ stdio: 'inherit' }, options));
+        process.on('exit', (exitCode) => {
+            if (exitCode === 0) {
+                resolve();
+            }
+            else {
+                reject();
+            }
+        });
+    });
+}
+exports.exec = exec;
+function rmIfExists(path) {
+    if ((0, fs_1.existsSync)(path)) {
+        (0, fs_1.rmSync)(path);
+    }
+}
+exports.rmIfExists = rmIfExists;
+function detectManager() {
+    switch ((0, path_1.basename)(process.env.npm_execpath || '')) {
+        case 'yarn.js':
+            return 'yarn';
+        case 'npx-cli.js':
+        case 'npm-cli.js':
+        default:
+            return 'npm';
+    }
+}
+exports.detectManager = detectManager;
+function normalizeOptions(options) {
+    const normalizedOptions = Object.assign({}, options);
+    if (normalizedOptions.npm && normalizedOptions.yarn) {
+        (0, logger_1.warn)(`Provided both ${(0, logger_1.highlight)('--yarn')} and ${(0, logger_1.highlight)('--npm')} flags, using ${(0, logger_1.choice)('--npm')}.`);
+        delete normalizedOptions.yarn;
+    }
+    if (!normalizedOptions.yarn) {
+        normalizedOptions.npm = true;
+    }
+    let fallbackOption = '--typescript';
+    const currentMutuallyExclusiveOptions = MUTUALLY_EXCLUSIVE_OPTIONS.filter((option) => normalizedOptions[option]);
+    if (normalizedOptions.source) {
+        fallbackOption = '--source';
+        delete normalizedOptions.example;
+        delete normalizedOptions.typescript;
+        delete normalizedOptions.javascript;
+    }
+    if (normalizedOptions.example) {
+        fallbackOption = '--example';
+        delete normalizedOptions.typescript;
+        delete normalizedOptions.javascript;
+    }
+    if (normalizedOptions.typescript) {
+        fallbackOption = '--typescript';
+        delete normalizedOptions.javascript;
+    }
+    if (!normalizedOptions.javascript) {
+        normalizedOptions.typescript = true;
+    }
+    if (currentMutuallyExclusiveOptions.length > 1) {
+        (0, logger_1.warn)(`Options ${(0, logger_1.highlight)('--source')}, ${(0, logger_1.highlight)('--example')}, ${(0, logger_1.highlight)('--typescript')} and ${(0, logger_1.highlight)('--javascript')} are mutually exclusive, using ${(0, logger_1.choice)(fallbackOption)}.`);
+    }
+    return normalizedOptions;
+}
+exports.normalizeOptions = normalizeOptions;

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "@contentful/create-contentful-app",
-  "version": "0.15.12",
+  "version": "1.1.0-alpha.10",
   "description": "A template for building Contentful Apps",
+  "keywords": [
+    "contentful",
+    "create-contentful-app"
+  ],
   "author": "Contentful GmbH",
   "license": "MIT",
   "repository": {
@@ -10,7 +14,7 @@
     "directory": "packages/contentful--create-contentful-app"
   },
   "engines": {
-    "node": ">=12",
+    "node": ">=14.15.0",
     "npm": ">=6"
   },
   "main": "lib/index.js",
@@ -25,34 +29,40 @@
   },
   "scripts": {
     "prettier": "prettier **/*.js --write --ignore-path .gitignore",
-    "lint": "eslint ./lib",
+    "lint": "eslint ./src",
     "lint:fix": "npm run lint -- --fix",
-    "pre-commit": "lint-staged"
+    "pre-commit": "lint-staged",
+    "build": "tsc"
   },
   "dependencies": {
-    "@contentful/app-scripts": "^0.15.8",
-    "@contentful/cra-template-create-contentful-app": "^0.15.4",
+    "@contentful/app-scripts": "^0.16.0-alpha.3",
     "chalk": "^4.1.0",
-    "contentful-management": "^8.0.0",
-    "create-react-app": "^5.0.0",
-    "cross-spawn": "^7.0.3",
-    "inquirer": "^8.0.0",
-    "open": "^8.0.1",
-    "tildify": "^2.0.0"
+    "commander": "^9.0.0",
+    "degit": "2.8.4",
+    "inquirer": "^8.2.1",
+    "rimraf": "^3.0.2",
+    "tildify": "^2.0.0",
+    "validate-npm-package-name": "^3.0.0"
   },
   "bugs": {
     "url": "https://github.com/contentful/create-contentful-app/issues"
   },
   "homepage": "https://github.com/contentful/create-contentful-app#readme",
-  "directories": {
-    "lib": "lib",
-    "test": "test"
-  },
   "files": [
     "lib"
   ],
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "5628de9ec655678824b98ca3360f77ff9ca914c8"
+  "devDependencies": {
+    "@tsconfig/node16": "^1.0.2",
+    "@types/chalk": "^2.2.0",
+    "@types/degit": "^2.8.3",
+    "@types/inquirer": "^8.2.0",
+    "@types/node": "^14.14.31",
+    "@types/rimraf": "^3.0.2",
+    "@types/tildify": "^2.0.2",
+    "@types/validate-npm-package-name": "^3.0.3"
+  },
+  "gitHead": "fb5a4faf89f78af13da791f60f549a27d416359a"
 }