Merge pull request #102 from netlify/addDetectors

add nextjs, hexo, gridsome, phenomic, docusaurus, brunch

Author: swyxio

README.md

@@ -26,6 +26,7 @@ This is how we pull down your build environment variables and manage your addons
 <summary>
 <b>Pro tip: Aliasing commands</b>
 </summary>
+
 As these commands are expected to be frequently used, it may be helpful to define aliases in your terminal (Mac: [bash](https://jonsuh.com/blog/bash-command-line-shortcuts/), [zsh](https://askubuntu.com/questions/758496/how-to-make-a-permanent-alias-in-oh-my-zsh), Windows: [doskey](https://stackoverflow.com/questions/20530996/aliases-in-windows-command-prompt), [registry](https://stackoverflow.com/questions/20530996/aliases-in-windows-command-prompt)) to your personal preference. For example:
 
 ```bash
@@ -39,18 +40,6 @@ alias ndx="netlify dev:exec "
 
 </details>
 
-## Live Share
-
-To share your ongoing dev session with a coworker, just run Netlify Dev with a `--live` flag:
-
-```bash
-netlify dev --live
-```
-
-You will get a URL that looks like `https://clever-cray-2aa156-6639f3.netlify.live/`. This can be accessed by anyone as long as you keep your session open.
-
-> Note: there are currently known issues with ending the live session alongside your webdevserver, as well as with live reloading. We are working on fixing it, and would appreciate repro cases. In the mean time you can run `ps aux | grep live-tunnel` and kill these sessions manually.
-
 ## Using the beta
 
 Currently the Netlify dev plugin is in private beta. You'll need to follow these steps to enable it:
@@ -97,14 +86,25 @@ COMMANDS
   dev:exec  Exec command
 ```
 
+## Live Share
+
+To share your ongoing dev session with a coworker, just run Netlify Dev with a `--live` flag:
+
+```bash
+netlify dev --live
+```
+
+You will get a URL that looks like `https://clever-cray-2aa156-6639f3.netlify.live/`. This can be accessed by anyone as long as you keep your session open.
+
+> Note: there are currently known issues with ending the live session alongside your webdevserver, as well as with live reloading. We are working on fixing it, and would appreciate repro cases. In the mean time you can run `ps aux | grep live-tunnel` and kill these sessions manually.
+
 ## Project detection
 
-Netlify Dev will attempt to detect the SSG or build command that you are using, and run these on your behalf, while adding other development utilities.
+Netlify Dev will attempt to detect the SSG or build command that you are using, and run these on your behalf, while adding other development utilities. If you have a JavaScript project, it looks for the best `package.json` script to run for you, using simple heuristics, so you can use the full flexibility of npm scripts. We may add more intelligence to this in future.
 
-**Overriding the detectors**: The number of project types which Netlify Dev can detect is growing, but if yours is not yet supported automatically, you can instruct Netlify Dev to run the project on your behalf by declaring it in a `[dev]` block of your `netlify.toml` file.
+**Overriding the detectors**: The number of [project types which Netlify Dev can detect](https://github.com/netlify/netlify-dev-plugin/tree/master/src/detectors) is growing, but if yours is not yet supported (contributions welcome!), you can instruct Netlify Dev to run the project on your behalf by declaring it in a `[dev]` block of your `netlify.toml` file.
 
 ```toml
-
 #sample dev block in the toml
 [dev]
   command = "yarn start" # Command to start your dev server
@@ -114,13 +114,13 @@ Netlify Dev will attempt to detect the SSG or build command that you are using,
 
 <details>
 <summary>
-<b>Explanation of detectors and ports in Netlify Dev</b>
+<b>Explanation of ports in Netlify Dev</b>
 </summary>
 
 There will be a number of ports that you will encounter when using Netlify Dev, especially when running a static site generator like Gatsby which has its own dev server. All the port numbers can be a bit confusing, so here is a brief explainer.
 
 - If your SSG has a devserver on port 8000 for example, Netlify Dev needs to be told to proxy that port so it can merge it in with the rest of the local Netlify environment (say, running on port 8888), which is what you want to get the full Netlify Dev experience with Functions, Redirects, and so on.
-- If you're running a project we have a detector for, we hardcode those conventional ports so you don't have to supply it yourself.
+- If you're running a project we have a detector for, we hardcode those conventional ports so you don't have to supply it yourself. If we have multiple detectors that match, we'll ask you to choose.
 - However, sometimes you're using some other project (we welcome contributions for detectors!) or just have a custom port you want Netlify Dev to point to for some reason. This is when you go to the `netlify.toml` `[dev]` block to specify exactly what port we should listen to.
 
 As for which port to use while doing local development in Netlify Dev, always look for this box in your console output and use that:

src/detectors/README.md

@@ -22,3 +22,47 @@
 - Dev block overrides will supercede anything you write in your detector: https://github.com/netlify/netlify-dev-plugin#project-detection
 - detectors are language agnostic. don't assume npm or yarn.
 - if default args (like 'develop') are missing, that means the user has configured it, best to tell them to use the -c flag.
+
+## detector notes
+
+- metalsmith is popular but has no dev story so we have skipped it
+- hub press doesnt even have cli https://github.com/HubPress/hubpress.io#what-is-hubpress
+- gitbook:
+
+not sure if we want to support gitbook yet
+
+requires a global install: https://github.com/GitbookIO/gitbook/blob/master/docs/setup.md
+
+```js
+const {
+  hasRequiredDeps,
+  hasRequiredFiles,
+  getYarnOrNPMCommand,
+  scanScripts
+} = require("./utils/jsdetect");
+module.exports = function() {
+  // REQUIRED FILES
+  if (!hasRequiredFiles(["README.md", "SUMMARY.md"])) return false;
+  // // REQUIRED DEPS
+  // if (!hasRequiredDeps(["hexo"])) return false;
+
+  /** everything below now assumes that we are within gatsby */
+
+  const possibleArgsArrs = [["gitbook", "serve"]];
+  // scanScripts({
+  //   preferredScriptsArr: ["start", "dev", "develop"],
+  //   preferredCommand: "hexo server"
+  // });
+
+  return {
+    type: "gitbook",
+    command: getYarnOrNPMCommand(),
+    port: 8888,
+    proxyPort: 4000,
+    env: { ...process.env },
+    possibleArgsArrs,
+    urlRegexp: new RegExp(`(http://)([^:]+:)${4000}(/)?`, "g"),
+    dist: "public"
+  };
+};
+```

src/detectors/brunch.js

@@ -0,0 +1,30 @@
+const {
+  hasRequiredDeps,
+  hasRequiredFiles,
+  getYarnOrNPMCommand,
+  scanScripts
+} = require("./utils/jsdetect");
+module.exports = function() {
+  // REQUIRED FILES
+  if (!hasRequiredFiles(["package.json", "brunch-config.js"])) return false;
+  // REQUIRED DEPS
+  if (!hasRequiredDeps(["brunch"])) return false;
+
+  /** everything below now assumes that we are within gatsby */
+
+  const possibleArgsArrs = scanScripts({
+    preferredScriptsArr: ["start"],
+    preferredCommand: "brunch watch --server"
+  });
+
+  return {
+    type: "brunch",
+    command: getYarnOrNPMCommand(),
+    port: 8888,
+    proxyPort: 3333,
+    env: { ...process.env },
+    possibleArgsArrs,
+    urlRegexp: new RegExp(`(http://)([^:]+:)${3333}(/)?`, "g"),
+    dist: "app/assets"
+  };
+};

src/detectors/docusaurus.js

@@ -0,0 +1,30 @@
+const {
+  hasRequiredDeps,
+  hasRequiredFiles,
+  getYarnOrNPMCommand,
+  scanScripts
+} = require("./utils/jsdetect");
+module.exports = function() {
+  // REQUIRED FILES
+  if (!hasRequiredFiles(["package.json", "siteConfig.js"])) return false;
+  // REQUIRED DEPS
+  if (!hasRequiredDeps(["docusaurus"])) return false;
+
+  /** everything below now assumes that we are within gatsby */
+
+  const possibleArgsArrs = scanScripts({
+    preferredScriptsArr: ["start"],
+    preferredCommand: "docusaurus-start"
+  });
+
+  return {
+    type: "docusaurus",
+    command: getYarnOrNPMCommand(),
+    port: 8888,
+    proxyPort: 3000,
+    env: { ...process.env },
+    possibleArgsArrs,
+    urlRegexp: new RegExp(`(http://)([^:]+:)${3000}(/)?`, "g"),
+    dist: "static"
+  };
+};

src/detectors/gridsome.js

@@ -0,0 +1,30 @@
+const {
+  hasRequiredDeps,
+  hasRequiredFiles,
+  getYarnOrNPMCommand,
+  scanScripts
+} = require("./utils/jsdetect");
+module.exports = function() {
+  // REQUIRED FILES
+  if (!hasRequiredFiles(["package.json", "gridsome.config.js"])) return false;
+  // REQUIRED DEPS
+  if (!hasRequiredDeps(["gridsome"])) return false;
+
+  /** everything below now assumes that we are within gridsome */
+
+  const possibleArgsArrs = scanScripts({
+    preferredScriptsArr: ["develop"],
+    preferredCommand: "gridsome develop"
+  });
+
+  return {
+    type: "gridsome",
+    command: getYarnOrNPMCommand(),
+    port: 8888,
+    proxyPort: 8080,
+    env: { ...process.env },
+    possibleArgsArrs,
+    urlRegexp: new RegExp(`(http://)([^:]+:)${8080}(/)?`, "g"),
+    dist: "static"
+  };
+};

src/detectors/hexo.js

@@ -0,0 +1,34 @@
+const {
+  hasRequiredDeps,
+  hasRequiredFiles,
+  getYarnOrNPMCommand,
+  scanScripts
+} = require("./utils/jsdetect");
+module.exports = function() {
+  // REQUIRED FILES
+  if (!hasRequiredFiles(["package.json", "_config.yml"])) return false;
+  // REQUIRED DEPS
+  if (!hasRequiredDeps(["hexo"])) return false;
+
+  /** everything below now assumes that we are within gatsby */
+
+  const possibleArgsArrs = scanScripts({
+    preferredScriptsArr: ["start", "dev", "develop"],
+    preferredCommand: "hexo server"
+  });
+
+  if (!possibleArgsArrs.length) {
+    // ofer to run it when the user doesnt have any scripts setup! 🤯
+    possibleArgsArrs.push(["hexo", "server"]);
+  }
+  return {
+    type: "hexo",
+    command: getYarnOrNPMCommand(),
+    port: 8888,
+    proxyPort: 4000,
+    env: { ...process.env },
+    possibleArgsArrs,
+    urlRegexp: new RegExp(`(http://)([^:]+:)${4000}(/)?`, "g"),
+    dist: "public"
+  };
+};

src/detectors/next.js

@@ -0,0 +1,34 @@
+const {
+  hasRequiredDeps,
+  hasRequiredFiles,
+  getYarnOrNPMCommand,
+  scanScripts
+} = require("./utils/jsdetect");
+module.exports = function() {
+  // REQUIRED FILES
+  if (!hasRequiredFiles(["package.json"])) return false;
+  // REQUIRED DEPS
+  if (!hasRequiredDeps(["next"])) return false;
+
+  /** everything below now assumes that we are within gatsby */
+
+  const possibleArgsArrs = scanScripts({
+    preferredScriptsArr: ["dev", "develop", "start"],
+    preferredCommand: "next"
+  });
+
+  if (!possibleArgsArrs.length) {
+    // ofer to run it when the user doesnt have any scripts setup! 🤯
+    possibleArgsArrs.push(["next"]);
+  }
+  return {
+    type: "next.js",
+    command: getYarnOrNPMCommand(),
+    port: 8888,
+    proxyPort: 3000,
+    env: { ...process.env },
+    possibleArgsArrs,
+    urlRegexp: new RegExp(`(http://)([^:]+:)${3000}(/)?`, "g"),
+    dist: "out"
+  };
+};

src/detectors/phenomic.js

@@ -0,0 +1,30 @@
+const {
+  hasRequiredDeps,
+  hasRequiredFiles,
+  getYarnOrNPMCommand,
+  scanScripts
+} = require("./utils/jsdetect");
+module.exports = function() {
+  // REQUIRED FILES
+  if (!hasRequiredFiles(["package.json"])) return false;
+  // REQUIRED DEPS
+  if (!hasRequiredDeps(["@phenomic/core"])) return false;
+
+  /** everything below now assumes that we are within gatsby */
+
+  const possibleArgsArrs = scanScripts({
+    preferredScriptsArr: ["start"],
+    preferredCommand: "phenomic start"
+  });
+
+  return {
+    type: "phenomic",
+    command: getYarnOrNPMCommand(),
+    port: 8888,
+    proxyPort: 3333,
+    env: { ...process.env },
+    possibleArgsArrs,
+    urlRegexp: new RegExp(`(http://)([^:]+:)${3333}(/)?`, "g"),
+    dist: "public"
+  };
+};