SharePoint Development : SPFx Folder Structure Explained

If you’re a SharePoint developer diving into the world of modern web parts or extensions, you’ve likely crossed paths with SPFx (SharePoint Framework). And if you’ve ever opened an SPFx solution in your code editor and asked yourself, “Why are there so many folders? What do they all do?” — you’re not alone.

Understanding the SPFx folder structure is more than just a rite of passage. It’s about being efficient, writing maintainable code, and following best practices that keep your projects scalable and professional.

Let’s break it down — in plain language — with practical insights, tips, use cases, and comparisons that matter.

🔍 What Is SPFx?

SPFx, or SharePoint Framework, is a modern development model for building custom experiences in SharePoint Online (and supported in SharePoint 2016/2019 with feature packs). It allows you to build:

Web parts
Extensions (Application Customizers, Command Sets, Field Customizers)
Microsoft Teams apps (yes, SPFx works here too!)

It uses modern web stack technologies: TypeScript, React, Node.js, Yeoman, Gulp — and integrates deeply with Microsoft 365.

🧭 Why Do We Need a Defined Folder Structure?

The SPFx folder structure helps:

Organize your code logically
Separate concerns like configuration, source code, assets, styles
Simplify build and deployment processes
Make onboarding easier for other developers

Without it, maintaining or scaling your solution becomes a nightmare.

👤 Who Uses SPFx?

Primarily:

SharePoint developers building custom UI and logic in SharePoint Online
Microsoft 365 consultants implementing tailored solutions
Power Platform professionals enhancing solutions via code
Frontend developers working within Microsoft 365 ecosystem

🗂️ SPFx Folder Structure Breakdown

When you scaffold a new SPFx project using Yeoman, here’s what you typically get:

my-spfx-project/
│
├── config/                # Build configuration files (JSON)
├── lib/                   # Transpiled JavaScript files (auto-generated)
├── node_modules/          # npm packages
├── src/                   # Your TypeScript source code (where the magic happens)
│   ├── webparts/          # Web part components
│   └── extensions/        # SPFx extensions (if any)
├── temp/                  # Intermediate build files (auto-generated)
├── sharepoint/            # Deployment assets (e.g., .sppkg)
├── teams/                 # Microsoft Teams app manifest (if Teams support is enabled)
├── package.json           # Project metadata, dependencies
├── tsconfig.json          # TypeScript configuration
├── gulpfile.js            # Gulp tasks (build automation)
└── README.md              # Project overview

Let’s focus on the most relevant parts:

`src/`

This is where your actual development takes place. You’ll typically work inside:

src/webparts/<yourWebPartName>/
src/extensions/<yourExtensionName>/

Each contains:

.ts files (main class, interfaces)
.manifest.json (component configuration)
.scss or .css files (styling)
loc/ (localization resources)

`config/`

Handles build and packaging configuration:

serve.json – Local dev server config
package-solution.json – Solution package settings
write-manifests.json, build.json, deploy-azure-storage.json – Deployment and bundling instructions

✅ Best Practices

Keep components small and modular
Don’t build everything in a single file. Use reusable components.
Use folders to group by feature, not type
Especially useful in larger projects: /src/features/webPartName/
Keep secrets/config out of version control
Use .gitignore wisely and keep your tokens, keys, etc., secured.
Leverage loc for localization
Always externalize strings to mystrings.d.ts to support multilingual SharePoint tenants.
Document your solution
Don’t underestimate a good README.md file.

🔁 Approaches: Feature-Folder vs Type-Folder

There are two common strategies:

📁 Type-based (default SPFx structure)

/src/
├── components/
├── services/
├── webparts/

Pros: Easy for small/medium projects
Cons: Hard to trace all parts of a feature in one place

📁 Feature-based (recommended for larger projects)

/src/features/
├── kudosWebPart/
│   ├── components/
│   ├── services/
│   ├── styles/

Pros: Keeps all related files together
Cons: Might feel “nested” early on, but pays off later

💡 Sample Use Case

Imagine you’re building a Kudos Web Part that posts thank-yous within a SharePoint site:

/src/features/kudosWebPart/
├── Kudos.tsx
├── IKudosProps.ts
├── KudosService.ts
├── styles/Kudos.module.scss
├── loc/en-us.js

You’re maintaining clean separation: UI, props, services, styles, and localization.

⚖️ SPFx vs Alternatives (and Their Structure)

Tech	Folder Structure	Strengths	Weaknesses
SPFx	Opinionated, modular	Integrated with SharePoint & Teams	Complex setup, config-heavy
PowerApps	App Studio UI	Low-code, quick solutions	Not suited for complex UI logic
PnP Script	Script-based	Great for automation/config	Not suitable for UI customization
React Standalone	Customizable	Total control, clean structure	Needs external hosting/deployment

📈 Pros and Cons of SPFx Structure

✅ Pros:

Well-defined, opinionated structure
Scalable and maintainable for large teams
Supports localization, testing, deployment

❌ Cons:

Initial learning curve
Gulp/Node dependency issues
Can get verbose for simple customizations

🧪 Sample Implementation

A simplified web part folder structure:

/webparts/helloWorld/
├── HelloWorldWebPart.ts
├── components/
│   └── HelloWorld.tsx
├── loc/
│   └── mystrings.d.ts
├── HelloWorld.module.scss
└── HelloWorld.manifest.json

You import the component like:

import HelloWorld from './components/HelloWorld';

Localize your UI:

import * as strings from 'HelloWorldWebPartStrings';

And style with:

.helloWorld {
  font-size: 16px;
}

🔗 Helpful Resources

Getting familiar with the SPFx folder structure is more than just a best practice — it’s a gateway to building powerful, scalable, and maintainable SharePoint solutions.

Whether you’re a solo developer or part of a large team, how you structure your code matters.

It affects:

How fast you build
How well others can contribute
How easily you can scale

So next time you open that /src/webparts/ folder — appreciate the architecture behind it.