This is a boilerplate project designed to streamline Webflow development using Vite. It includes a modular structure for animations, page-specific routing, and customization options to fit various project needs.
- Overview
- Features
- Getting Started
- Development Workflow
- Setting Up Environment Variables
- Usage
- Folder Structure
- Advanced Configuration
- Production Build
- Contributing
- License
- Credits
- Acknowledgments
The Balky Webflow Starter is a comprehensive starter template that integrates modern development tools like Vite with Webflow. This boilerplate helps you manage custom code, modular animations, and page-specific scripts efficiently. It's designed to prevent code leakage, enhance performance, and simplify the development process.
- Vite Integration: Utilizes Vite for fast development, real-time updates, and efficient builds.
- Modular Animations: Organized structure for managing animations, including general animations and page-specific animations (e.g., Home, About).
- Page Routing: Implements a flexible page routing system using
data-page-nameattributes to initialize animations only on relevant pages. - Customizability: Easily extend the router and animation setup to suit specific project needs, including options for custom attributes and hooks.
To get started with the Balky Webflow Starter, you'll need:
- A Webflow account and project
- Basic knowledge of HTML, CSS, and JavaScript
- (Optional) A GitHub account for easier integration with CodeSandbox
-
Clone the Repository:
If you're comfortable with Git, you can clone the repository:
git clone https://github.com/CarterOgunsola/balky-webflow-starter.git
Alternatively, you can download the ZIP file from the GitHub repository and extract it on your computer.
-
Choose Your Development Environment:
You have two options for development: using CodeSandbox (recommended for beginners) or setting up a local development environment.
CodeSandbox is a cloud-based development environment that's easy to use and requires no local setup.
- Go to CodeSandbox and create an account if you don't have one.
- Click on "Create Sandbox" and choose "Import Project".
- Paste the URL of this GitHub repository:
https://github.com/CarterOgunsola/balky-webflow-starter - CodeSandbox will automatically set up the project and install dependencies.
- Once the sandbox is ready, you'll see a preview of your project and can start editing the files.
-
In your CodeSandbox project, look for the URL in the address bar. It should look something like
https://xxxxxxxx.csb.app. -
Go to your Webflow project and open the project settings.
-
In the "Custom Code" section, add the following to the
<head>tag:<script type="module" src="https://xxxxxxxx.csb.app/@vite/client"></script> <script type="module" src="https://xxxxxxxx.csb.app/js/index.js"></script>
Replace
https://xxxxxxxx.csb.appwith your actual CodeSandbox URL. -
Save and publish your Webflow project.
-
You should now see your changes in real-time as you edit in CodeSandbox.
If you prefer to develop locally:
- Ensure you have Node.js installed on your computer.
- Open a terminal and navigate to the project folder.
- Install dependencies:
npm install # or if you prefer yarn yarn install - Start the development server:
npm run dev # or yarn dev - You'll see a local URL (usually
http://localhost:3000). Use this URL in your Webflow project's custom code section as described in the CodeSandbox instructions above.
If your project requires API keys or other sensitive information:
- Copy the
.env.templatefile and rename it to.env.local. - Open
.env.localand add your variables:VITE_GSAP_API_KEY=your_gsap_api_key_here - In your code, access these variables like this:
const gsapApiKey = import.meta.env.VITE_GSAP_API_KEY;
Remember: Never commit .env.local to version control.
In your Webflow project, add the data-page-name attribute to the main wrapper of each page:
<body>
<div data-page-name="home" class="page-wrapper">
<!-- Page content here -->
</div>
</body>For basic projects, use the simple router in your index.js:
import { initPageRouter } from "./utils/pageRouter";
document.addEventListener("DOMContentLoaded", () => {
initPageRouter();
});For more complex projects:
import { initPageRouter } from "./utils/pageRouter";
initPageRouter({
attributeName: "data-custom-page",
defaultPage: "home",
onBeforeInit: (pageName) => console.log(`Starting animations for: ${pageName}`),
onAfterInit: (pageName) => console.log(`Finished initializing animations for: ${pageName}`),
});- Add general animations in
/animations/general/. - For page-specific animations, create a new folder under
/animations/(e.g.,/animations/contact/) with anindex.jsfile.
src/
├── js/
│ ├── animations/
│ │ ├── general/
│ │ ├── home/
│ │ └── about/
│ ├── utils/
│ └── index.js
└── styles/
└── index.css
Refer to the Advanced Configuration section in the original README for details on custom attributes, hooks, and edge case handling.
When you're ready to deploy:
-
Run the build command:
npm run build # or yarn build -
The generated
index.jsfile needs to be hosted. Options include:- Upload to Webflow as a
.txtfile (renameindex.jstoindex.js.txt). - Use a CDN like jsDelivr (upload to GitHub and use the jsDelivr URL).
- Host on Cloudflare or other CDN services.
- Upload to Webflow as a
-
Update your Webflow project's custom code to use the hosted file:
<script type="text/javascript" src="https://your-hosted-file-url.js"></script>
We welcome contributions! Please see the Contributing section in the original README for guidelines.
This project is licensed under the MIT License. See the LICENSE file for details.
Based on the Vite Webflow Starter by Oluwadare Seyi.
- Thanks to the Webflow community for support and inspiration.
- Created with ❤️ by Carter Ogunsola and the Balky Studio team.