Welcome to the SaaShovel Documentation! This guide provides
everything you need to know to set up, customize, and get the most out of SaaShovel. Whether
you're just getting started or looking to explore advanced features, this documentation will
help you make the most of your SaaS experience with SaaShovel.
Check out our GitHub repository for the latest code and updates.
Development Environment:
We recommend using one of these options for the best development experience:
- Laravel Herd (Windows/macOS) - fastest native environment
- Laravel Sail (all platforms) - Docker-based solution
- Laragon (Windows) - full-featured local server
- Laravel Valet (macOS) - lightweight option
- Laravel Homestead (all platforms) - VM-based environment
Note: Make sure all PHP extensions are installed and enabled before proceeding with the installation. You can check your PHP configuration by running php -m in your terminal.
Clone the SaaShovel repository (or download it from GitHub). You will need to generate a PAT (Personal Access Token). More information on how to generate it can be found here.
Navigate to the SaaShovel folder
Copy the ".env.example" file and rename it to ".env" to configure your app. More information is provided below in point 5.
Install PHP dependencies
Install Node.js dependencies
Then
This command will:
Change the host url in the "vite.config.js" file to your local dev url.
ThenFinally
Update your .env file with the following settings:
The names must strictly match (case-sensitive) the subscription tier names you've set in your billing provider's dashboard.
Pro Tip: For a Step By Step guide on how to create subscription plans, please click here
Remember to never commit your .env file to version control. Keep your API keys and secrets secure!
Pro Tip: Most configuration options can be modified through:
Main folders to customize:
Make sure to review the documentation before making significant changes. Each component is documented with its available props and usage examples.
SaaShovel provides several custom artisan commands to streamline your development workflow:
Initialize your SaaShovel project
This command will:
Reset your application to a clean state
This command will:
Pro Tip: Use saashovel:flush during development to quickly reset your application state. Be careful not to use it in production as it will erase all data!
Generate a new Livewire page component with proper structure
This command will create:
Delete all subscription plans from the database (useful for a plan data refresh)
This command will:
Set up application for development mode
This command will:
Pro Tip: After running saashovel:dev, don't forget to start the Vite development server with npm run dev. Review the development checklist to ensure everything is properly configured.
Deploy application to production mode
This command will:
Pro Tip: Use saashovel:prod when deploying to production. Make sure to review the post-deployment checklist displayed after completion. Always test in a staging environment first!
SaaShovel supports multiple payment processors, configurable via the
BILLING_PROVIDER environment variable.
Configure multiple payment methods by:
BILLING_PROVIDER=paddle)
For exclusive cryptocurrency payments, set
BILLING_PROVIDER=nowpayments
SaaShovel automatically handles the entire subscription process. Users can manage their subscriptions through:
All providers include a "Cancel Plan" button for easy subscription cancellation.
Features:
Note: For pricing plan design customization, please refer to the Components section of this documentation.
.env file, ensuring all necessary
variables are set..env file match exactly with your provider's
dashboard.FIRST_TIER_SUBSCRIPTION_NAME,
SECOND_TIER_SUBSCRIPTION_NAME, or
THIRD_TIER_SUBSCRIPTION_NAMESTRIPE_KEY
in your .envSTRIPE_SECRETcustomer.subscription.* events)STRIPE_WEBHOOK_SECRET in your .envFIRST_TIER_SUBSCRIPTION_NAME,
SECOND_TIER_SUBSCRIPTION_NAME, or
THIRD_TIER_SUBSCRIPTION_NAMELEMON_SQUEEZY_API_KEY in your
.env#XXXXXX) without the "#"
LEMON_SQUEEZY_STORE in your .env
LEMON_SQUEEZY_SIGNING_SECRET in your .env
FIRST_TIER_SUBSCRIPTION_NAME,
SECOND_TIER_SUBSCRIPTION_NAME, or
THIRD_TIER_SUBSCRIPTION_NAMEPADDLE_VENDOR_IDPADDLE_VENDOR_AUTH_CODEPADDLE_PUBLIC_KEYPADDLE_CLIENT_SIDE_TOKENPADDLE_WEBHOOK_SECRETPADDLE_SANDBOX=true in your .envFIRST_TIER_SUBSCRIPTION_NAME,
SECOND_TIER_SUBSCRIPTION_NAME, or
THIRD_TIER_SUBSCRIPTION_NAME.env:
NOWPAYMENTS_EMAILNOWPAYMENTS_PASSWORDNOWPAYMENTS_API_KEYNOWPAYMENTS_IPN_SECRETNOWPAYMENTS_CURRENCY
(e.g., USD)NOWPAYMENTS_BASE_URL=https://api-sandbox.nowpayments.io/v1/
Webhook listeners are located in the app/Listeners/ directory.
Handled through Laravel's Cashier package.
Implemented using the LemonSqueezy Laravel package.
Managed by SaaShovel's proprietary package
(tcja/nowpayments-laravel).
Testing Webhooks Locally:
SaaShovel provides flexibility in changing billing providers without service interruption.
In case of billing provider issues (e.g., account suspension), you can:
BILLING_PROVIDER to an alternative provider.While the app supports multiple billing providers simultaneously:
Note: While multiple provider support offers flexibility, maintaining subscriptions across different providers may lead to complex database records. Consider consolidating to a single provider (or the hybrid method with NOWPayments) for cleaner data management.
The application uses two main layouts located in resources/views/layouts:
app.blade.php - This layout is used when users are logged into their
dashboard.
guest.blade.php - This layout is used for:
The navigation menu is implemented in two locations:
resources/views/components/navigation-menu.blade.php (for dashboard
layout)resources/views/components/header.blade.php (for public layout)
<!-- Blog menu code -->
@php $menu = \LaraZeus\Sky\SkyPlugin::get()->getModel('Navigation')::fromHandle('main'); @endphp
@if($menu && $menu->items)
@foreach($menu->items as $item)
{!! \App\CustomRenderNavItem::render($item, $menuLinkClass) !!}
@endforeach
@endif
<!-- /Blog menu code -->
This code automatically displays pages created through the CMS. The default menu handle is "main".
Add links manually below the CMS menu code:
<!-- Site links -->
<div class="bg-gray-100 p-4 rounded-md font-mono text-sm mt-2">
<a href="#features" class="class">Features</a>
<a href="#pricing" class="class">Pricing</a>
</div>
<!-- /Site links -->
Note: When creating menus through the CMS, ensure you use the "main" handle for the menu to display properly, or update the handle in the code if you prefer a different name.
Saashovel supports automatic locale detection based on browser settings. Configure this in your .env file:
Tip: Set APP_USE_BROWSER_LOCALE to true to automatically serve content in the user's preferred language.
The application uses Laravel's standard JSON-based localization system. Locale files are organized in different locations based on their purpose:
resources/lang/
resources/lang/vendor/zeus-sky/
resources/lang/vendor/zeus-wind/
Note: Saashovel comes with multiple language translations out of the box. Make sure to:
Users with admin rights are automatically redirected to the admin panel upon login. The
panel consists of several tabs, each serving specific administrative functions.
It is powered by the powerful Filament
package.
Features integrated Google Analytics widgets. To enable:
GOOGLE_ANALYTICS_WIDGETS=true in your .env file to display
widgets
Comprehensive user management interface for adding, removing, and updating user
data.
Impersonate users to assist them with any issues they encounter by clicking on the