@netlify/framework-info

What is @netlify/framework-info?

@netlify/framework-info is an npm package designed to provide information about various web frameworks. It helps in detecting the framework used in a project and provides relevant details, which can be useful for deployment and configuration purposes.

What are @netlify/framework-info's main functionalities?

Detect Framework

This feature allows you to detect the framework used in a given project directory. The `getFramework` function returns details about the detected framework, such as its name and version.

const { getFramework } = require('@netlify/framework-info');

async function detectFramework() {
  const framework = await getFramework({
    projectDir: process.cwd(),
  });
  console.log(framework);
}

detectFramework();

List All Frameworks

This feature provides a list of all frameworks that the package can detect. The `listFrameworks` function returns an array of framework objects, each containing details like name, category, and detection criteria.

const { listFrameworks } = require('@netlify/framework-info');

async function listAllFrameworks() {
  const frameworks = await listFrameworks();
  console.log(frameworks);
}

listAllFrameworks();

0

README

Framework detection utility.

Detects which framework a specific website is using. The framework's build/dev commands, directories and server port are also returned.

The following frameworks are detected:

• Static site generators: Gatsby, Hugo, Jekyll, Next.js, Nuxt, Hexo, Gridsome, Docusaurus, Eleventy, Middleman, Phenomic, React-static, Stencil, Vuepress, Assemble, DocPad, Harp, Metalsmith, Roots, Wintersmith
• Front-end frameworks: create-react-app, Vue, Sapper, Angular, Ember, Svelte, Expo, Quasar
• Build tools: Parcel, Brunch, Grunt, Gulp

If you're looking for a way to run framework-info via CLI check the build-info project.

Additions and updates are welcome!

Example (Node.js)

import { listFrameworks, hasFramework, getFramework } from '@netlify/framework-info'

console.log(await listFrameworks({ projectDir: './path/to/gatsby/website' }))
// [
//   {
//     id: 'gatsby',
//     name: 'Gatsby',
//     category: 'static_site_generator',
//     dev: {
//       commands: ['gatsby develop'],
//       port: 8000,
//       pollingStrategies: [{ name: 'TCP' }, { name: 'HTTP' }]
//     },
//     build: {
//       commands: ['gatsby build'],
//       directory: 'public'
//     },
//     staticAssetsDirectory: "static",
//     env: { GATSBY_LOGGER: 'yurnalist' },
//     plugins: []
//   }
// ]

console.log(await listFrameworks({ projectDir: './path/to/vue/website' }))
// [
//   {
//     id: 'vue',
//     name: 'Vue.js',
//     category: 'frontend_framework',
//     dev: {
//       commands: ['npm run serve'],
//       port: 8080,
//       pollingStrategies: [{ name: 'TCP' }, { name: 'HTTP' }]
//     },
//     build: {
//       commands: ['vue-cli-service build'],
//       directory: 'dist'
//     },
//     env: {},
//     plugins: []
//   }
// ]

console.log(await hasFramework('vue', { projectDir: './path/to/vue/website' }))
// true

console.log(await getFramework('vue', { projectDir: './path/to/vue/website' }))
// {
//   id: 'vue',
//   name: 'Vue.js',
//   category: 'frontend_framework',
//   dev: {
//     commands: ['npm run serve'],
//     port: 8080,
//     pollingStrategies: [{ name: 'TCP' }, { name: 'HTTP' }]
//   },
//   build: {
//     commands: ['vue-cli-service build'],
//     directory: 'dist'
//   },
//   env: {},
//   plugins: []
// }

Installation

npm install @netlify/framework-info

Usage (Node.js)

listFrameworks(options?)

options: object?
Return value: Promise<object[]>

Options

projectDir

Type: string
Default value: process.cwd()

Path to the website's directory.

Return value

This returns a Promise resolving to an array of objects describing each framework. The array can be empty, contain a single object or several objects.

Each object has the following properties.

id

Type: string

Id such as "gatsby".

name

Type: string

Framework name such as "Gatsby".

category

Type: string

Category among "static_site_generator", "frontend_framework" and "build_tool".

dev

Type: object

Information about the dev command.

commands

Type: string[]

Dev command. There might be several alternatives.

port

Type: number

Server port.

pollingStrategies

Type: object[]

Polling strategies to use when checking if the dev server is ready.

build

Type: object

Information about the build command.

commands

Type: string[]

Build command. There might be several alternatives.

directory

Type: string

Relative path to the directory where files are built.

staticAssetsDirectory

Type: string

Directory where the framework stores static assets. Can be undefined.

env

Type: object

Environment variables that should be set when calling the dev command.

plugins

Type: string[]

A list of recommend Netlify build plugins to install for the framework.

hasFramework(frameworkId, options?)

options: object?
Return value: Promise<boolean>

Same as listFramework() except only for a specific framework and returns a boolean.

getFramework(frameworkId, options?)

options: object?
Return value: Promise<object>

Same as listFramework() except the framework is passed as argument instead of being detected. A single framework object is returned.

Usage (CLI)

$ framework-info [projectDirectory]

This prints the ids of each framework.

If known is found, unknown is printed.

Available flags:

• --long: Show more information about each framework. The output will be a JSON array.

Add or update a framework

Each framework is a JSON file in the /src/frameworks/ directory. For example:

{
  "id": "gatsby",
  "name": "Gatsby",
  "category": "static_site_generator",
  "detect": {
    "npmDependencies": ["gatsby"],
    "excludedNpmDependencies": [],
    "configFiles": ["gatsby-config.js"]
  },
  "dev": {
    "command": "gatsby develop",
    "port": 8000,
    "pollingStrategies": [{ "name": "TCP" }, { "name": "HTTP" }]
  },
  "build": {
    "command": "gatsby build",
    "directory": "public"
  },
  "staticAssetsDirectory": "static",
  "env": { "GATSBY_LOGGER": "yurnalist" },
  "plugins": []
}

All properties are required.

id

Type: string

Id of the framework.

name

Type: string

Name of the framework.

category

Type: string

One of "static_site_generator", "frontend_framework" or "build_tool".

detect

Type: object

Information used to detect this framework

npmDependencies

Type: string[]

Framework's npm packages. Any project with one of those packages in their package.json (dependencies or devDependencies) will be considered as using the framework.

If empty, this is ignored.

excludedNpmDependencies

Type: string[]

Inverse of npmDependencies. If any project is using one of those packages, it will not be considered as using the framework.

If empty, this is ignored.

configFiles

Type: string[]

Framework's configuration files. Those should be paths relative to the project's directory. Any project with one of configuration files will be considered as using the framework.

If empty, this is ignored.

dev

Type: object

Parameters to detect the dev command.

command

Type: string

Default dev command.

port

Type: number

Local dev server port.

pollingStrategies

Type: object[]

Polling strategies to use when checking if the dev server is ready.

build

Type: object

Parameters to detect the build command.

command

Type: string

Default build command.

directory

Type: string

Directory where built files are written to.

staticAssetsDirectory

Type: string

Directory where the framework stores static assets where relevant for the framework.

env

Type: object

Environment variables that should be set when running the dev command.

plugins

Type: object[]

A list of Netlify build plugins package names and conditions. If a condition is met for a plugin it will be returned in the framework's plugin's list.

For example

{
  "plugins": [
    {
      "packageName": "@netlify/plugin-nextjs",
      "condition": { "minNodeVersion": "10.13.0" }
    }
  ]
}