next compose plugins next compose plugins

NEXT-COMPOSE-PLUGINS

Bietet eine sauberere API zum Aktivieren und Konfigurieren von Plugins für Next.js, da die Standard -Way Next.js vorschlägt, Plugins zu aktivieren und zu konfigurieren, können unklar und verwirrend werden, wenn Sie viele Plugins haben.

Es ist oft unklar, welche Plugins aktiviert sind oder welche Konfiguration zu welchem Plugin gehört, da sie verschachtelt sind und ein Konfigurationsobjekt teilen. Dies kann auch zu verwaisten Konfigurationswerten führen, wenn Plugins aktualisiert oder entfernt werden.

Während next-compose-plugins versucht, diesen Fall zu beseitigen, indem eine alternative API zum Aktivieren und Konfigurieren von Plugins bereitgestellt wird, bei denen jedes Plugin über ein eigenes Konfigurationsobjekt verfügt, fügt es auch weitere Funktionen wie phasenspezifische Plugins und Konfiguration hinzu.

Inhaltsverzeichnis

Installation
Verwendung
- withPlugins
- Optionale Plugins
- Eine andere Konfigurationsdatei erweitern
Plugin -Entwickler
Beispiele
Siehe auch
Lizenz

Installation

 npm install --save next-compose-plugins

Erstellen eines Armaturenbretts oder einer Administrator -Benutzeroberfläche ? Oder möchten Sie in einem realen Projekt ein Nutzungsbeispiel für next-compose-plugins sehen? Schauen Sie sich das NextJS -Material -Dashboard von unseren Partnern Creative Tim an, um Ihnen den Einstieg zu erleichtern.

Verwendung

 // next.config.js
const withPlugins = require ( 'next-compose-plugins' ) ;

module . exports = withPlugins ( [ ... plugins ] , nextConfiguration ) ;

`plugins`

In den Beispielen finden Sie weitere Anwendungsfälle.

Es ist ein Array, das alle Plugins und deren Konfiguration enthält. Wenn ein Plugin keine zusätzliche Konfiguration benötigt, können Sie einfach das importierte Plugin hinzufügen. Wenn es eine Konfiguration benötigt oder Sie sie nur in einer bestimmten Phase ausführen möchten, können Sie ein Array angeben:

`[plugin: function, configuration?: object, phases?: array]`

`plugin: function`

Importiertes Plugin. Sehen Sie sich den Abschnitt Optional Plugins an, wenn Sie nur ein Plugin benötigen möchten, wenn es wirklich verwendet wird.

 const withPlugins = require ( 'next-compose-plugins' ) ;
const sass = require ( '@zeit/next-sass' ) ;

module . exports = withPlugins ( [
  [ sass ] ,
] ) ;

`configuration?: object`

Konfiguration für das Plugin.

Sie können auch bestimmte Konfigurationsschlüssel für eine Phase überschreiben:

 const withPlugins = require ( 'next-compose-plugins' ) ;
const { PHASE_PRODUCTION_BUILD } = require ( 'next/constants' ) ;
const sass = require ( '@zeit/next-sass' ) ;

module . exports = withPlugins ( [
  [ sass , {
    cssModules : true ,
    cssLoaderOptions : {
      localIdentName : '[path]___[local]___[hash:base64:5]' ,
    } ,
    [ PHASE_PRODUCTION_BUILD ] : {
      cssLoaderOptions : {
        localIdentName : '[hash:base64:8]' ,
      } ,
    } ,
  } ] ,
] ) ;

Dadurch werden die cssLoaderOptions mit dem neuen localIdentName überschreiben, jedoch nur während der Produktionsaufbau. Sie können auch mehrere Phasen kombinieren ( [PHASE_PRODUCTION_BUILD + PHASE_PRODUCTION_SERVER]: {} ) oder eine Phase ausschließen ( ['!' + PHASE_PRODUCTION_BUILD]: {} , die die Konfiguration in allen Phasen mit Ausnahme PRODUCTION_BUILD ) überschreibt. Sie können alle Phasen als Next.js verwenden.

`phases?: array`

Wenn das Plugin nur in bestimmten Phasen angewendet werden sollte, können Sie diese hier angeben. Sie können alle Phasen als Next.js verwenden.

 const withPlugins = require ( 'next-compose-plugins' ) ;
const { PHASE_DEVELOPMENT_SERVER , PHASE_PRODUCTION_BUILD } = require ( 'next/constants' ) ;
const sass = require ( '@zeit/next-sass' ) ;

module . exports = withPlugins ( [
  [ sass , {
    cssModules : true ,
    cssLoaderOptions : {
      localIdentName : '[path]___[local]___[hash:base64:5]' ,
    } ,
  } , [ PHASE_DEVELOPMENT_SERVER , PHASE_PRODUCTION_BUILD ] ] ,
] ) ;

Sie können die Phasen auch mit einem führenden ! :

 const withPlugins = require ( 'next-compose-plugins' ) ;
const { PHASE_DEVELOPMENT_SERVER , PHASE_PRODUCTION_BUILD } = require ( 'next/constants' ) ;
const sass = require ( '@zeit/next-sass' ) ;

module . exports = withPlugins ( [
  [ sass , {
    cssModules : true ,
    cssLoaderOptions : {
      localIdentName : '[path]___[local]___[hash:base64:5]' ,
    } ,
  } , [ '!' , PHASE_DEVELOPMENT_SERVER ] ] ,
] ) ;

Dadurch wird das Plugin in allen Phasen mit Ausnahme PHASE_DEVELOPMENT_SERVER angewendet.

`nextConfiguration`

Jede direkte Konfiguration von Next.js kann hierher gehen, zum Beispiel: {distDir: 'dist'} .

Sie können auch die Webpack -Konfiguration von Next.js in diesem Objekt anpassen.

 const withPlugins = require ( 'next-compose-plugins' ) ;

const nextConfig = {
  distDir : 'build' ,
  webpack : ( config , options ) => {

    // modify the `config` here

    return config ;
  } ,
} ;

module . exports = withPlugins ( [
  // add plugins here..
] , nextConfig ) ;

Phasen werden auch innerhalb des nächsten Objekts nextConfiguration unterstützt und haben die gleiche Syntax wie in Plugin configuration .

 const { PHASE_DEVELOPMENT_SERVER } = require ( 'next/constants' ) ;
const nextConfig = {
  distDir : 'build' ,
  [ '!' + PHASE_DEVELOPMENT_SERVER ] : {
    assetPrefix : 'https://my.cdn.com' ,
  } ,
} ;

Optionale Plugins

Wenn ein Plugin nur dann geladen wird, wenn es verwendet wird, können Sie die optional Helferfunktion verwenden. Dies kann insbesondere dann nützlich sein, wenn das Plugin nur in den devDependencies liegt und daher möglicherweise nicht in allen Phasen verfügbar ist. Wenn Sie den optional Helfer in diesem Fall nicht verwenden, erhalten Sie einen Fehler.

 const { withPlugins , optional } = require ( 'next-compose-plugins' ) ;
const { PHASE_DEVELOPMENT_SERVER } = require ( 'next/constants' ) ;

module . exports = withPlugins ( [
  [ optional ( ( ) => require ( '@zeit/next-sass' ) ) , { /* optional configuration */ } , [ PHASE_DEVELOPMENT_SERVER ] ] ,
] ) ;

Eine andere Konfigurationsdatei erweitern

Es ist manchmal sinnvoll, eine next.config.js -Datei in mehrere Dateien aufzuteilen, beispielsweise wenn Sie mehr als nur ein Next.js -Projekt in einem Repository haben. Sie können dann die Basiskonfiguration in einer Datei definieren und projektspezifische Plugins/Einstellungen in der Konfigurationsdatei oder im Projekt hinzufügen.

Um dies einfach zu archivieren, können Sie den extend -Helfer in der next.config.js -Datei Ihres Projekts verwenden.

 // next.config.js
const { withPlugins , extend } = require ( 'next-compose-plugins' ) ;
const baseConfig = require ( './base.next.config.js' ) ;

const nextConfig = { /* ... */ } ;

module . exports = extend ( baseConfig ) . withPlugins ( [
  [ sass , {
    cssModules : true ,
  } ] ,
] , nextConfig ) ;

 // base.next.config.js
const withPlugins = require ( 'next-compose-plugins' ) ;

module . exports = withPlugins ( [
  [ typescript , {
    typescriptLoaderOptions : {
      transpileOnly : false ,
    } ,
  } ] ,
] ) ;

Plugin -Entwickler

Dieses Plugin hat einige zusätzliche Funktionen, die Sie als Plugin -Entwickler verwenden können. Wenn Sie sie jedoch verwenden, sollten Sie irgendwo in Ihrem Readme erwähnen oder Anweisungen installieren, die next-compose-plugins benötigt, um alle Funktionen verfügbar zu haben. Daher wird Ihre Benutzer nicht verwirren, wenn etwas nicht wie beschrieben funktioniert, da sie dieses Kompose-Plugin noch nicht verwenden.

Phasen

Sie können angeben, in welchen Phasen Ihr Plugin in dem von Ihnen zurückgegebenen Objekt ausgeführt werden soll:

 const { PHASE_DEVELOPMENT_SERVER } = require ( 'next/constants' ) ;

module . exports = ( nextConfig = { } ) => {
  return Object . assign ( { } , nextConfig , {
    // define in which phases this plugin should get applied.
    // you can also use multiple phases or negate them.
    // however, users can still overwrite them in their configuration if they really want to.
    phases : [ PHASE_DEVELOPMENT_SERVER ] ,

    webpack ( config , options ) {
      // do something here which only gets applied during development server phase

      if ( typeof nextConfig . webpack === 'function' ) {
        return nextConfig . webpack ( config , options ) ;
      }

      return config ;
    } ,
  } ;
} ;

Diese Phasen werden als Standardkonfiguration behandelt und Benutzer können die Phasen in ihrer next.config.js -Datei überschreiben, wenn sie möchten. Weitere verfügbare Optionen finden Sie in der Phasenkonfiguration.

Weitere Informationen

Wenn ein Plugin mit next-compose-plugins geladen wird, sind einige zusätzliche Informationen, von denen Sie abhängen können, verfügbar. Es wird als zweites Argument an Ihre Plugin -Funktion weitergegeben:

 module . exports = ( nextConfig = { } , nextComposePlugins = { } ) => {
  console . log ( nextComposePlugins ) ;
} ;

Derzeit enthält es diese Werte:

 {
  // this is always true when next-compose-plugins is used
  // so you can use this as a check when your plugin depends on it
  nextComposePlugins : boolean ,

  // the current phase which gets applied
  phase : string ,
}

Beispiele

Beispiel für reale Welt

Schauen Sie sich das NextJS-Material-Dashboard von unseren Partnern Creative Tim an, um zu sehen, wie next-compose-plugins in einer realen Weltanwendung verwendet wurde.

Grundlegendes Beispiel

 // next.config.js
const withPlugins = require ( 'next-compose-plugins' ) ;
const images = require ( 'next-images' ) ;
const sass = require ( '@zeit/next-sass' ) ;
const typescript = require ( '@zeit/next-typescript' ) ;

// next.js configuration
const nextConfig = {
  useFileSystemPublicRoutes : false ,
  distDir : 'build' ,
} ;

module . exports = withPlugins ( [

  // add a plugin with specific configuration
  [ sass , {
    cssModules : true ,
    cssLoaderOptions : {
      localIdentName : '[local]___[hash:base64:5]' ,
    } ,
  } ] ,

  // add a plugin without a configuration
  images ,

  // another plugin with a configuration
  [ typescript , {
    typescriptLoaderOptions : {
      transpileOnly : false ,
    } ,
  } ] ,

] , nextConfig ) ;

Erweitertes Beispiel

 // next.config.js
const { withPlugins , optional } = require ( 'next-compose-plugins' ) ;
const images = require ( 'next-images' ) ;
const sass = require ( '@zeit/next-sass' ) ;
const typescript = require ( '@zeit/next-typescript' ) ;

const {
  PHASE_PRODUCTION_BUILD ,
  PHASE_PRODUCTION_SERVER ,
  PHASE_DEVELOPMENT_SERVER ,
  PHASE_EXPORT ,
} = require ( 'next/constants' ) ;

// next.js configuration
const nextConfig = {
  useFileSystemPublicRoutes : false ,
  distDir : 'build' ,
} ;

module . exports = withPlugins ( [

  // add a plugin with specific configuration
  [ sass , {
    cssModules : true ,
    cssLoaderOptions : {
      localIdentName : '[local]___[hash:base64:5]' ,
    } ,
    [ PHASE_PRODUCTION_BUILD + PHASE_EXPORT ] : {
      cssLoaderOptions : {
        localIdentName : '[hash:base64:8]' ,
      } ,
    } ,
  } ] ,

  // add a plugin without a configuration
  images ,

  // another plugin with a configuration (applied in all phases except development server)
  [ typescript , {
    typescriptLoaderOptions : {
      transpileOnly : false ,
    } ,
  } , [ '!' , PHASE_DEVELOPMENT_SERVER ] ] ,

  // load and apply a plugin only during development server phase
  [ optional ( ( ) => require ( '@some-internal/dev-log' ) ) , [ PHASE_DEVELOPMENT_SERVER ] ] ,

] , nextConfig ) ;

Vergleich

Zum Vergleich würde es ohne dieses Plugin so aussehen, wo es nicht wirklich klar ist, welche Konfiguration zu welchem Plugin und zu welchen aktivierten Plugins ist. Viele oben genannte Funktionen sind ebenfalls nicht möglich oder müssen viel mehr benutzerdefinierten Code in Ihrer Konfigurationsdatei haben.

 // next.config.js
const withSass = require ( '@zeit/next-sass' ) ;
const withTypescript = require ( '@zeit/next-typescript' ) ;
const withImages = require ( 'next-images' ) ;
const withOffline = require ( 'next-offline' ) ;

module . exports = withSass ( withOffline ( withTypescript ( withImages ( {
    {
        cssModules : true ,
        cssLoaderOptions : {
            importLoaders : 1 ,
            localIdentName : '[local]___[hash:base64:5]' ,
        } ,
        typescriptLoaderOptions : {
            transpileOnly : false ,
        } ,
        useFileSystemPublicRoutes : false ,
        distDir : 'build' ,
        workerName : 'sw.js' ,
        imageTypes : [ 'jpg' , 'png' ] ,
    }
} ) ) ) ) ;