How to set up the Newspack Starter Template for custom plugins

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.

Prefer to have this handled for you? The Newspack team can create and configure the repository on your behalf – the repo itself, the deploy pipeline, and the per-site SFTP credentials – so you can skip straight to writing code. If you’d rather we set it up than follow the steps below yourself, just reach out to us.

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 template is built to 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. A pre-configured build process: Powered by the @wordpress/scripts package, ensuring compatibility with WordPress standards. Refer to the official documentation for configuration options.
2. PHP CodeSniffer configuration: Automatically enforces Newspack coding standards.
3. An easy way to create Modules, that will help to keep the code organized and flexible
4. Prettier configuration: Ensures consistent code formatting for WordPress.
5. Husky integration: Lints local file changes before they are committed.
6. GitHub Actions for code standards: Checks that commits and merges adhere to coding guidelines.
7. 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.
8. Automated deployment to production: Merges to the release branch triggers a deployment to the production environment.
9. Automated deployment to staging: Pushing to the alpha branch triggers a deployment to a staging environment.
10. Automated build processes for deploys: When deploying to staging or production servers, the vendor and build directories are automatically created.

How To Use the Template

Follow these steps to set up your repository using the Newspack Starter Template:

1. Create a New Repository

• Navigate to the Newspack Plugin Starter Template repository on GitHub.
• Click on the “Use this template” button to create a new repository in your GitHub account.

2. Set Up Secrets and Variables for Deployment

Note: The Newspack team has tooling that can perform this entire step for you automatically, including creating the SFTP user and the target folder on each site. This section documents what that tooling sets up, in case you need to do it by hand.

Deployment works on a per-site basis: every site you deploy to is a separate WordPress install with its own SFTP credentials. One repository can deploy to any number of sites; you simply register each site once. For each site you add a secret pair (in this step) and an entry in a list variable (further below).

• Go to Settings > Secrets and Variables > Actions in your new repository.
• In the Repository secrets section, add a username/password pair for each site. The SITE_NAME portion is a suffix you choose to identify the site (for example SEVENDAYSVT_COM); it must match the suffix you use in the variables below.

Repeat this for every site. A publisher with one production site and one staging site has two secret pairs; a publisher with a network of sites has one pair per site.

• Navigate to the “Variables” tab and create one variable called PROD_SITES and another called STAGING_SITES.
• In each of these variables, enter a JSON-formatted array listing the site suffixes you want to deploy to (the same suffixes you used in the secrets). The deploy workflow loops over this array and pushes the plugin to every site in it.
  • Single site: ["DALILYNEWS_COM"]
  • Multiple sites: ["PUBLICATION_A","PUBLICATION_B","PUBLICATION_C"]

• To add a new site later, just add its secret pair and add its suffix to the relevant variable’s array. No workflow changes are needed.

3. 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.

4. 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).

5. 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.

6. 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

7. 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

8. Deploy

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

• Pushing changes to the alpha branch deploys to every site listed in STAGING_SITES.
• Pushing changes to the release branch deploys to every site listed in PROD_SITES.

9. Enable your custom modules!

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