Clone the GitHub template
View full version
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)
- Go to project repository → Settings → Secrets and variables → Actions
- New repository secret: Name
NPM_TOKEN, paste token
- 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)
- Go to project repository → Settings → Secrets and variables → Actions
- New repository secret: Name
PERSONAL_ACCESS_TOKEN, paste PAT
- 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:- Fix the linting errors shown in terminal
- Stage fixes with
git add - 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.
2️⃣ Automated Method (Recommended):
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):
PageScripts: Add before page </body> closing tag
Styles: Add in page <head> tag
Project Code (Global):
GlobalScripts: Add before global </body> closing tag, under Script Loader.
Styles: Add in global <head> tag, under Style Loader.
Shipping to NPM
Post-Shipment Steps:
Automated: UpdatenpmPath with your own path in the global <head>.
Traditional:
Replace local script tags located in global and page-specific </body> to:
<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.