The Newspack Plugin Starter Template is a pre-configured starting point for custom plugin development on the Newspack platform. It provides essential tools to streamline the development process and maintain coding standards.

As part of onboarding to our custom development program, the Newspack team will create and configure the repository on your behalf.

A single repository created from this template holds all the custom code for one publisher. Because a publisher may run more than one site (for example a production site and a staging site, or a network of several publications), the can deploy the same plugin to multiple sites from one repository: you list each target site in the deploy configuration, and a single merge deploys to all of them at once.

When using this template for custom development, keep changes in pull requests and review them with both GitHub status checks and Copilot-assisted code review before merging.

What Does It Provide?

This template includes:

  1. Guidance for AI tools: An AGENTS.md file explaining to your coding agent how to best develop on top of Newspack and follow best practices.
  2. A pre-configured build process: Powered by the @wordpress/scripts package, ensuring compatibility with WordPress standards. Refer to the official documentation for configuration options.
  3. PHP CodeSniffer configuration: Automatically enforces Newspack coding standards.
  4. An easy way to create Modules, that will help to keep the code organized and flexible
  5. Prettier configuration: Ensures consistent code formatting for WordPress.
  6. Husky integration: Lints local file changes before they are committed.
  7. GitHub Actions for code standards: Checks that commits and merges adhere to coding guidelines.
  8. Repository-level GitHub Copilot instructions: The template includes .github/copilot-instructions.md so Copilot code review has Newspack and WordPress-specific guidance when reviewing pull requests.
  9. Automated deployment to production: Merges to the release branch triggers a deployment to the production environment.
  10. Automated deployment to staging: Pushing to the alpha branch triggers a deployment to a staging environment.
  11. Automated build processes for deploys: When deploying to staging or production servers, the vendor and build directories are automatically created.

Onboarding

Follow these steps to get set up a code repository:

1. Reach out to Newspack support to get onboarded onto our custom development program.

The Newspack team will create and set up a GitHub repo for you with the necessary deploy workflows for production and staging. We’ll then transfer it to your organization’s GitHub account. You will own the code repository.

2. Configure Branch Protection Rules

  • Navigate to Settings > Branches.
  • Click on Add classic branch protection rule.
  • Enter trunk into the Branch name pattern field.
  • Check Require a pull request before merging.
  • Check Require approvals.
    • You can leave the number of required approvals set at 1.
  • Check Require status checks to pass before merging.
  • In the search box, searching for “Linting” and add each status check that appears.
    • There should be 3 in total.

Recommended: Request a GitHub Copilot review

For custom development pull requests, we strongly recommend requesting a GitHub Copilot code review before merging. To do this, open the pull request in GitHub and add Copilot as a reviewer in the Reviewers section.

A Copilot review can help catch WordPress, Newspack, security, performance, and deployment issues early. It is an additional safeguard, not a replacement for required human approval or passing status checks.

The starter template includes .github/copilot-instructions.md, which provides Copilot with Newspack-specific review guidance.

You can also add a ruleset to the repository so Copilot reviews pull requests automatically.

3. Add Newspack Team as Collaborators

  • Navigate to Settings > Collaborators and Teams.
  • Add the Newspack team as collaborators with write access.
  • If necessary, add team members individually (get their GitHub usernames from the Newspack team).

4. Clone and Set Up Locally

  • Open a terminal and run the following commands:
git clone YOUR_REPO
cd YOUR_REPO
npm run setup
  • This installs all dependencies and prepares the development environment.

5. Create and Push alpha and release Branch

  • In your terminal, run the following command to create alpha and release branches:
git checkout -b alpha
git push origin alpha

git checkout -b release
git push origin release

6. Start Developing!

  • Begin building your custom plugin using the pre-configured development environment.
  • Use npm start for local development and npm run build for production.
  • Be sure to do a find and replace in the codebase to change the default PublisherName and publisher-name strings to something more appropriate for your organization.
  • Add your own code as new Modules. Check the Sample module under inc/Modules, rename or copy it and then discard it. The module.php files under the modules folders are automatically loaded

7. Deploy

Deploying to your sites is as easy as merging changes to branches.

  • Pushing changes to the alpha branch deploys to every staging site.
  • Pushing changes to the release branch deploys to every production site.

8. Enable your custom modules!

Go to Settings > Custom Modules and enable the modules you are developing!