Quick Start

  • Alexandro Martínez
    Author
    by Alexandro Martínez
    2 years ago
  • On this quick-start tutorial, you'll get a glimpse of every SaasRock feature.

    Requirements:

    Steps

    1. Installation

    💿 1.1. Install all the dependencies:

    npm install

    If you get any issues, try with yarn.

    💿 1.2. Rename the .env.example file to → .env.

    💿 1.3. Seed the database:

    npx prisma migrate dev --name init

    You should get the following output:

    🌱  The seed command has been executed.

    If you get any issues, try updating the database and seeding manually:

    npx prisma db push
    npx prisma db seed

    By default, the codebase seeds the following data (using the prisma/seed.ts file):

    • 1 admin user: Credentials are defined by the ADMIN_EMAIL and ADMIN_PASSWORD env variables.

    • 2 tenant users: john.doe@company.com and luna.davis@company.com.

    • 2 tenants: Acme Corp 1 and Acme Corp 2.

    • 1 linked account between these tenants.

    • 2 blog posts.

    • 2 custom entities: Employee and Contract.

    NOTE

    If you're using sqlite, you can restart your database by deleting the generated prisma/dev.db file + the prisma/migrations folder, and run the command again.

    💿 1.4. Start the application:

    npm run dev
    

    Open localhost:3000, you'll see the landing page:

    Landing Page Hero

    💿 1.5. Switch to Dark Mode and Select the Spanish language from the Navbar items:

    Dark mode and Spanish Hero

    2. Set up Subscription Plans

    💿 2.1. Set up the STRIPE_SK env variable and restart the app. Click here to view your Stripe secret key.

    💿 2.2. Log in as your admin user (ADMIN_EMAIL and ADMIN_PASSWORD env variables).

    You will see the Admin Dashboard:

    Admin Dashboard

    💿 2.3. Click on "Pricing → Set up", or click the sidebar item "Set up → Pricing Plans".

    Pricing Plans

    NOTE

    You can change the default pricing plans on the plans.server.ts file

    💿 2.4. Click on "Click here to create them".

    Navigate to your Stripe Dashboard to see the created Products:

    Stripe Products

    💿 2.5. Visit your Pricing page at /pricing.

    You will see the recently created pricing plans:

    Pricing

    3. Set up Transactional Email Templates (OPTIONAL)

    NOTE

    You can skip this step, but you will not get emails. To skip this step, make sure you don't set the env variable values of POSTMARK_SERVER_TOKEN and POSTMARK_FROM_EMAIL.

    💿 3.1. Create a Postmark account if you haven't already, they have the best development experience for transactional emails (you can use the code REMIXSAASPOSTMARK for -20%).

    💿 3.2. Create an email server.

    New Postmark Server

    💿 3.3. Click on "API Tokens", copy the Server API token, and set it to the POSTMARK_SERVER_TOKEN env variable.

    💿 3.4. Add a Domain or Sender signature and set it to the POSTMARK_FROM_EMAIL env variable.

    NOTE

    In order to use a valid email, you will be asked to verify the domain ownership with TXT and CNAME records.

    Domain VerificationDomain Verified

    💿 3.5. Restart the app, log in as your admin user, and click on "Set up → Email Templates".

    You can override the default templates at the /public/emails folder.

    Email Templates

    💿 3.6. Click on "Create all".

    Navigate to your Postmark Templates to confirm they were created:

    Postmark Email Templates

    4. Creating an Account

    💿 4.1. Go to the /register page, and create an account with a valid email.

    If you didn't skip the previous, you should get a Welcome email:

    Welcome email

    💿 4.2. Click on "Login".

    You will be redirected to the App portal Dashboard at /app/:your-tenant-name/dashboard:

    App Portal Dashboard

    Note there are 3 main sections:

    • Sidebar

      • Sidebar Menu: The sidebar items are loaded on the app/application/sidebar/AppSidebar.tsx file.

      • Current tenant: Same behavior as the Search bar.

    • Top

      • Search bar: This button opens up the Command palette (switch accounts, logout...). You can customize the commands on the app/components/ui/commandPalettes/AppCommandPalette.tsx component.

      • Top Left Buttons: Subscription, Linked accounts, and Profile buttons.

    • Content

      • Dashboard: By default, it loads a summary of the application Custom Entities: Contracts and Employees. You can customize the dashboard on the app/routes/app.$tenant/dashboard.tsx route component.

    5. Use the App Portal

    💿 5.1. Go to "Settings → Profile", and change your name and avatar.

    Profile Settings

    💿 5.2. Go to "Settings → Members", and invite yourself with another valid email.

    New Member

    If you didn't step 3, you should get an Invitation email:

    Invitation email

    And if you click on the "Set up account" button, it will redirect you to set a password (if you do this, log out and log in as the admin user for this tenant):

    Set up account

    💿 5.3. Go to "Settings → Subscription", and subscribe to the "Free" plan, it will redirect you to a Stripe Checkout page, use any testing card.

    My Subscription

    💿 5.4. Try to add another user, it should not let you since the "Free plan" includes 2 users only.

    Upgrade Subscription

    💿 5.5. Go back to "Settings → Subscription", upgrade your plan, and try to add another user. This time you should not get any warnings.

    💿 5.5. Go to "Settings → Account", and change the account/tenant name, slug and icon.

    NOTE

    I changed the account slug to acme-corp-3, notice how it redirected me to /app/acme-corp-3/settings/account.

    Upgrade Account

    💿 5.6. Go to "Settings → Audit Trails".

    You should see at least 3 events:

    1. We subscribed to the Free plan.

    2. We upgraded our plan.

    3. We updated the account details.

    Audit Trails

    6. Using the Autogenerated Views and Forms

    By default, the codebase seeds the Entity model with: Employee and Contract.

    • Employee - Has 4 dynamic properties: First name, Last name, Email, and Salary.

    • Contract - Has 4 hard-coded properties (DB model columns): Name, Description, Status, and File.

    These 2 entities will help you understand the Entity Builder feature.

    💿 6.1. Go to "Employees".

    This is an autogenerated table view for the Entity "Employee", we plan to add more views: Kanban, Grid, and more.

    Employees

    💿 6.2. We don't have any employees, so click on New.

    New employee

    💿 6.3. Edit the employee.

    You should now have 2 audit trails: Created and Updated.

    NOTE

    You can also see these events at /app/:tenant/settings/audit-trails.

    Edit employee

    7. Adding a Custom Property

    Let's say we want our SaaS users to add employee's documents, we need a property of type "MEDIA".

    💿 7.1. Log out, log in as your admin user, go to "Entities", and click on the Employee properties cell.

    Employee Properties

    💿 7.2. Click on "Add new field" and set the following values.

    Define these values:

    • Type: Media.

    • Title: Documents.

    • Name: documents.

    Added Documents Property

    💿 7.3. Click on the "Switch to app" sidebar item, or log out and log in as your tenant user.

    💿 7.4. Go to "Employees", and click on "New".

    💿 7.4. Edit any employee, and add 1 PDF and 1 image to the new property field (Documents).

    WARNING

    Currently, there are 2 supported file type preview: PDF's and images (click on the eye icon to preview a file).

    Edited Documents Field

    8. Adding Employees to Google Sheets using Webhooks

    💿 8.1. As an admin user, go to /admin/entities/employees/webhooks.

    As you can see, there are 3 supported events for Webhooks: Created, Updated, and Deleted. But you can add your own, just use the createRowLog function with a custom action.

    Employee Entity Webhooks

    💿 8.2. In a new tab, create a new Webhooks by Zapier zap, with the Trigger Event: Catch Hook.

    Webhooks by Zapier

    💿 8.3. Copy the Custom Webhook URL.

    💿 8.4. Go back to the Employee's Webhooks and click on Edit for the Created event.

    💿 8.5. Paste the Zapier Custom Webhook URL hook on the Endpoint field, and save.

    Webhook Endpoint

    💿 8.6. Create another Employee at the /app portal.

    This should call the webhook endpoint.

    NOTE

    Customize the webhook calls on the callEntityWebhooks function.

    💿 8.7. Go back to the Zapier's zap creator, and test the trigger.

    As you can see, the webhook call was received successfully.

    Test Trigger

    💿 8.8. Create a Google Sheet document on Google Drive, name it "Employees", and add the headers: First name, Last name, Email, Salary, and Documents.

    Google Sheet

    💿 8.9. Select the "Create Spreadsheet Row" Google Sheets Action.

    NOTE

    You can hook with any application you want: Notion, Airtable, Dropbox...

    💿 8.10. Select your sheet, and link the corresponding properties, and turn on your Zap.

    Google Sheet Fields

    💿 8.11. Finally, add another employee and verify that the webhook is called.

    Added Employee to Google Sheet

    9. Using the autogenerated API

    💿 9.1. As a tenant user, generate a new API Key at /app/:tenant/settings/api/keys/new.

    Generate a new API Key

    💿 9.2. Click on Copy to clipboard, and save it somewhere (you'll use it on step 9.4).

    Copy to clipboard

    💿 9.3. Install Thunder Client for VS Code.

    💿 9.4. Create a new request with the following values:

    💿 9.5. Call the API by clicking "Send".

    Send GET API request

    💿 9.6. Test the POST, GET (/:id), PUT, and DELETE methods as you might expect them to work (or follow this guide).

    10. Customizing the Views and Forms

    The Contract model is the best of both worlds, Custom Entity and Custom Views and Forms.

    If you want to create another database model from scratch, follow this guide.

    💿 10.1. Go to "Settings → Linked Accounts → New", and create a link:

    New linked account

    You could also create another account with a valid email to get the following email:

    Link invitation email

    💿 10.2. Log in as that tenant, and accept the invitation.

    Accept link invitation

    💿 10.3. Create a contract:

    • Linked Account: Created linked account

    • Name: Contract 1

    • Description: Lorem ipsum...

    • File: Any PDF file

    • Signatories: Select 2 signatories (required)

    • Employees: Select at least 1 employee (optional)

    Create a Contract

    Once created, you should get an email:

    Contract Email

    💿 10.4. Finally, go to your dashboard.

    You should have at least 2 stats: Total Employees and Total Contracts.

    Dashboard

    I hope this quick guide was useful! Let me know if you have any questions.

    We respect your privacy.

    TLDR: We use cookies for language selection, theme, and analytics. Learn more.