Skip to main content

Clone the GitHub template

View full version

Webflow DevKit banner by Reform Digital

Installation

1

Setup Template

  • Click on “Use this template” in GitHub and clone as private repository.
  • Open locally with GitHub Desktop and open project in Visual Studio Code.
2

Setup NPM

  • Create NPM account
  • Generate NPM Granular Access Token with read/write permissions
  • Set Token Expiration: 30-90 days (recommended: 30 days)
  • Copy NPM Token (not retrievable later)
Add NPM Token to GitHub Secrets:For Solo Developers:
  • Go to project repository → Settings → Secrets and variables → Actions
  • New repository secret: Name NPM_TOKEN, paste token
For Organization Teams:
  • Option A (Free): Add to each repository’s secrets
  • Option B (Paid): Add to organization secrets (requires paid plan)
3

Setup Access Token

  • Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
  • Generate new token (classic)
  • Configure scopes: repo, workflow, write:packages, read:packages
  • Copy token immediately (not retrievable later)
Add PAT to GitHub Secrets:For Solo Developers:
  • Go to project repository → Settings → Secrets and variables → Actions
  • New repository secret: Name PERSONAL_ACCESS_TOKEN, paste PAT
For Organization Teams:
  • Option A (Free): Add to each repository’s secrets
  • Option B (Paid): Add to organization secrets (requires paid plan)
4

Setup VS Code

Install pnpm: (Skip if already installed)
Install dependencies:

How to Use DevKit™

Building & Testing

Run a Local Development Server:

Run a Local Production Server:

Pre-commit Hooks

Automatic Code Quality

Pre-commit hooks automatically format and lint your code before commits:
  • Prettier formats JavaScript and CSS files in src/
  • ESLint catches and auto-fixes errors
  • Commit blocked if ESLint errors are found
  • Auto-setup when running pnpm install

Troubleshooting

If commit is blocked:
  1. Fix the linting errors shown in terminal
  2. Stage fixes with git add
  3. Commit again

Importing Scripts

1️⃣ Traditional Method:

  • Operation: Run your local server using pnpm dev or pnpm prod.
  • Script Logging: DevKit™ logs script tags for JavaScript and CSS files from the src folder.
  • Integration: Manually copy and paste script tags to your Webflow pages or global settings, being mindful to switch between development and production tags as needed.

Core DevKit™ Scripts (Global):

Main Settings: Add in global <head> tag
Style-Loader: Add in global <head> tag
Script-Loader: Add before global </body> closing tag

Project Code (Page level):

Page Scripts: Add before page </body> closing tag
Page Styles: Add in page <head> tag

Project Code (Global):

Global Scripts: Add before global </body> closing tag, under Script Loader.
Global Styles: Add in global <head> tag, under Style Loader.

Shipping to NPM

If you are using the GitHub extension for VS Code, grant the necessary permissions if prompted.

Post-Shipment Steps:

Automated: Update npmPath with your own path in the global <head>. Traditional: Replace local script tags located in global and page-specific </body> to:
Replace local style tags in global and page-specific <head> to:

Addressing Caching

@latest Versioning

  • Initial Release: @latest (or omitting @version) is ok for initial release.
  • Subsequent Releases: @latest might lead to outdated content due to CDN and browser caching.

Cache Management

  • CDN Cache: Manually purge via jsDelivr’s Purge Tool.
  • Browser Cache: Educate users; no direct control, can only hard refresh or clear own browser cache.

Use Specific Versions to Prevent Caching Issues

  • Automated Import: npm path "@your-npm-username/your-package-name@version"
  • Traditional Import: src path "https://cdn.jsdelivr.net/npm/@your-npm-username/your-package-name@version/your-filename.js"

Branches & Collab

Single Developer Workflow

  • Initial Development: Work directly in main branch.
  • Creating a Dev Branch: After initial release, create a dev branch.
  • Routine Development: Work in dev, commit changes, push commits.
  • Merging and Releasing: Merge dev into main, publish to npm.

Multi-Developer Collaboration Workflow

  • Setting Up Main and Dev Branches: Ensure main and dev branches are set up.
  • Creating Feature Branches: Developers create feature branches from dev.
  • Development, Commit, Push: Work on feature, commit, and push.
  • Collaboration and Code Review: Open pull requests, review code, merge into dev.
  • Syncing Changes: Regularly fetch and merge changes from dev to avoid conflicts.
  • Adding Collaborators: Project maintainers can add collaborators through GitHub settings.
  • Preparing for Release: Merge dev into main, prepare for npm release.
  • Shipping to npm: Switch to main, fetch latest, pull changes, publish to npm.

Conclusion

  • Single developer workflow for smaller projects or initial phases.
  • Multi-developer collaboration workflow for larger teams and complex projects.