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.