Organizations & Projects

Understanding how to effectively manage organizations and projects is key to getting the most out of Parslinks. This guide covers everything you need to know.

Organizations

Organizations are the top-level entity in Parslinks. They serve as containers for projects, team members, and billing.

What is an Organization?

An organization represents a company, team, or group that owns and manages projects. Each organization has:

• Unique Identity: Slug and custom branding
• Team Members: Users with different roles and permissions
• Projects: All applications and websites
• Billing: Subscription plan and payment method
• Settings: Shared configuration across projects

Creating an Organization

1. Navigate to the organization selector in the top navigation
2. Click Create New Organization
3. Fill in the required information:

Organization Name: Acme Corporation
Organization Slug: acme
Description: Our company's web projects (optional)

4. Select a plan (Free, Pro, Team, or Enterprise)
5. Click Create Organization

Organization Settings

Access organization settings from the sidebar:

General Settings

• Name: Display name for your organization
• Slug: URL identifier (e.g., acme.parslinks.app)
• Logo: Upload organization logo
• Description: Brief description of your organization
• Website: Your company website

Domain Settings

• Default Domain: Base domain for all projects
• Custom Root Domain: Use your own domain (e.g., deploy.yourcompany.com)
• Preview Domain Pattern: Template for preview URLs

Security Settings

• Two-Factor Authentication: Require 2FA for all members
• IP Allowlist: Restrict access by IP address
• SSO: Configure single sign-on (Enterprise)
• Audit Logs: Track all organization activity

Switching Organizations

If you're a member of multiple organizations:

1. Click the organization name in the top navigation
2. Select the organization you want to switch to
3. The dashboard will update to show that organization's data

Transferring Organizations

To transfer ownership:

1. Go to Settings → General
2. Scroll to Transfer Organization
3. Enter the new owner's email
4. Confirm the transfer
5. The new owner must accept the transfer

Deleting an Organization

⚠️ Warning: This action is irreversible!

To delete an organization:

1. Go to Settings → General
2. Scroll to Danger Zone
3. Click Delete Organization
4. Type the organization slug to confirm
5. All projects, domains, and data will be permanently deleted

Projects

Projects are individual applications or websites within an organization.

What is a Project?

A project represents a single application or website. Each project has:

• Source Code: Connected Git repository (optional)
• Build Configuration: Framework, commands, environment
• Deployments: Build history and versions
• Domains: Custom domains and URLs
• Environment Variables: Configuration per environment
• Team Access: Specific member permissions

Creating a Project

Method 1: Quick Create

1. Click New Project from the dashboard
2. Enter project name and select framework
3. Click Create for instant setup with defaults

Method 2: Import from Git

1. Click Import Project
2. Connect your Git provider (GitHub, GitLab, Bitbucket)
3. Select repository
4. Configure build settings
5. Deploy

Method 3: Deploy from Template

1. Click New Project → Use Template
2. Browse available templates
3. Select a template (Next.js app, React dashboard, etc.)
4. Customize and deploy

Project Structure

Each project has several key components:

Production Environment

• Live Deployment: Currently active deployment
• Production URL: Main URL for your site
• Production Branch: Git branch that auto-deploys to production

Preview Environments

• Pull Request Previews: Automatic deployments for PRs
• Branch Previews: Deploy specific branches
• Unique URLs: Each preview gets its own URL

Development Settings

• Framework: Next.js, React, Vue, etc.
• Root Directory: Project root (for monorepos)
• Build Command: Command to build your project
• Output Directory: Where built files are located
• Install Command: How to install dependencies
• Development Command: Local development command

Project Configuration

General Settings

Project Name: My Awesome App
Project Slug: awesome-app
Framework: Next.js
Root Directory: apps/web (for monorepos)
Node Version: 18.x
Package Manager: npm / yarn / pnpm

Build Settings

# Build Settings
Build Command: npm run build
Output Directory: .next
Install Command: npm install

# Development Settings (optional)
Development Command: npm run dev
Dev Port: 3000

Git Settings

Repository: github.com/yourorg/yourrepo
Production Branch: main
Enable Auto Deploy: Yes
Enable Preview Deployments: Yes
Preview Branch Pattern: * (all branches)

Project Environments

Projects can have multiple environments:

Production

• Purpose: Live, customer-facing deployment
• Branch: Usually main or master
• URL: project.yourdomain.com
• Auto Deploy: Enabled by default

Preview

• Purpose: Test changes before production
• Branch: Feature branches and pull requests
• URL: project-git-branch.yourdomain.com
• Auto Deploy: On pull request creation

Development

• Purpose: Local development environment
• Configuration: Environment variables for local dev
• No Deployment: Runs on your local machine

Managing Projects

Pausing a Project

Temporarily stop deployments:

1. Go to Project Settings → General
2. Click Pause Project
3. Existing deployments remain accessible
4. New deployments are prevented

Archiving a Project

Archive projects you no longer need:

1. Go to Project Settings → General
2. Click Archive Project
3. Project is hidden from main list
4. Can be restored later

Deleting a Project

⚠️ Warning: This permanently deletes all deployments and data!

1. Go to Project Settings → General
2. Scroll to Danger Zone
3. Click Delete Project
4. Type project name to confirm
5. Project and all associated data are deleted

Project Templates

Parslinks offers templates for quick project setup:

Available Templates

• Next.js: E-commerce, dashboard, landing page
• React: SPA, PWA, component library
• Vue: Nuxt, Vite, SPA
• Svelte: SvelteKit, vanilla Svelte
• Static: HTML, Jekyll, Hugo
• Node.js: Express API, REST API

Using a Template

1. Click New Project → Templates
2. Browse by framework or use case
3. Click Deploy Template
4. Customize settings
5. Deploy and start building

Monorepo Support

Parslinks fully supports monorepo projects:

Configuring Monorepo Projects

// Example: Turborepo with multiple apps
Root Directory: apps/web
Build Command: cd ../.. && npm run build --filter=web
Output Directory: apps/web/.next

Multiple Projects from One Repository

You can deploy multiple projects from the same repository:

1. Create first project and set root directory (e.g., apps/web)
2. Create second project from same repo
3. Set different root directory (e.g., apps/admin)
4. Both projects deploy independently

Build Caching for Monorepos

• Turborepo: Automatic cache detection
• Nx: Native support for caching
• Lerna: Build cache supported
• Custom: Configure cache directories

Project Permissions

Control who can access each project:

Project-Level Access

Assigning Project Access

1. Go to Project Settings → Team
2. Select member
3. Choose access level
4. Save changes

Best Practices

Naming Conventions

✅ Good Names:
- my-portfolio
- api-gateway
- web-frontend

❌ Avoid:
- project1
- test
- asdfgh

Organization Structure

Small Team (1-5 people)

Organization: company-name
├── Production Projects
├── Staging Projects
└── Personal Projects

Medium Team (5-20 people)

Organization: company-name
├── Product A
│   ├── Frontend
│   ├── Backend
│   └── Admin
└── Product B
    ├── Web
    └── Mobile API

Large Team (20+ people)

Organization: engineering
├── Customer-Facing
├── Internal Tools
└── Microservices

Organization: marketing
├── Landing Pages
└── Campaign Sites

Project Organization Tips

1. Use Descriptive Names: Make it clear what each project does
2. Consistent Naming: Follow a naming pattern across projects
3. Separate Environments: Use projects for different environments if needed
4. Archive Old Projects: Keep your project list clean
5. Document Projects: Add descriptions and README links

Limits by Plan

Different plans have different limits:

Frequently Asked Questions

Can I move a project between organizations?

Yes, you can transfer projects:

1. Go to Project Settings → General
2. Click Transfer Project
3. Select destination organization
4. Confirm transfer

How do I rename a project?

1. Go to Project Settings → General
2. Update Project Name
3. Update Project Slug (will change URLs)
4. Save changes

Can I have multiple organizations?

Yes! You can create or be invited to multiple organizations. Switch between them using the organization selector.

What happens when I delete an organization?

All projects, deployments, domains, and data are permanently deleted. Team members lose access. This cannot be undone.

Can I use my own domain for all projects?

Yes! Configure a custom root domain in organization settings, and all projects will use subdomains of your domain.

Next Steps