NPMPublishPlugin

A Publish plugin that makes it easy to run npm commands for any Publish website.

Table of Contents

• Introduction
  • Requirements
  • Installation
• Usage
  • Configuring npm
  • Running npm commands
  • On Argument
• References
• License

Introduction

NPMPublishPlugin allows you to integrate an NPM package into your Publish site. If you require javascript or css to be built for your site, this is the ideal plugin for you.

Requirements

Apple Platforms

• Xcode 14.3 or later

• Swift 5.8 or later

• macOS 12 or later deployment targets

Linux

• Ubuntu 18.04 or later
• Swift 5.8 or late

Installation

To install it into your Publish package, add it as a dependency within your Package.swift manifest:

let package = Package(
  ...
  dependencies: [
      ...
      .package(
         url: "https://github.com/johnsundell/publish.git", 
         from: "0.9.0"
      ),
      .package(
        url: "https://github.com/brightdigit/NPMPublishPlugin.git",
        from: "1.0.0"
      )
  ],
  targets: [
    .target(
      ...
      dependencies: [
          ...
          .product(name: "Publish", package: "publish"),
          .product(name: "NPMPublishPlugin", package: "NPMPublishPlugin"),
      ]
    )
  ]
  ...
)

Then import NPMPublishPlugin wherever you’d like to use it:

import NPMPublishPlugin

Usage

Add the npm to your Publish steps:

import NPMPublishPlugin

let mainJS = OutputPath.file("js/main.js")

try DeliciousRecipes().publish(using: [
    .addMarkdownFiles(),
    .copyResources(),
    .addFavoriteItems(),
    .addDefaultSectionTitles(),
    .generateHTML(withTheme: .delicious),
    .generateRSSFeed(including: [.recipes]),
    .generateSiteMap(),
    // from the **npm** package directory at `Styling`
    .npm(npmPath, at: "Styling") {
      // run `npm ci`
      ci()
      // run `npm run publish -- --output-filename js/main.js`
      run(paths: [mainJS]) {
        "publish -- --output-filename"
        mainJS
      }
    }
])

Configuring npm

NPMPublishPlugin includes three ways to create a Publish step to run npm.

Firstly, you can supply a Settings and an array of Job items. However most likely you’ll want to to use the other two methods which you can pass:

• an optional path to the npm command
• an optional path to the current directory to run from as either a Folder or Path object from Publish
• using the NPM/JobBuilder pass the series jobs similar to how SwiftUI builds a View using its DSL

Running npm commands

NPMPublishPlugin comes with two commands ci and run. If you wish to include more commands, simply create a function which can take in Arguments similar to the run method:

public func run(
  paths: [OutputPath] = [],
  @NPM.ArgumentBuilder _ arguments: () -> [NPM.Argument]
) -> NPM.Job {
  .init(subcommand: .run, outputRelativePaths: paths, arguments)
}

On Argument

The Argument item can be either a simple string or an OutputPath that’s dynamic and based a Path from the Publish library.

References

• Publish by John Sundell
• npm

License

This code is distributed under the MIT license. See the LICENSE file for more info.