Getting Started

Welcome to ShipClojure! This guide will help you get your development environment set up and running quickly.

Prerequisites

1. Install mise for managing development environment tools

2. Clone the ShipClojure repository and set up your own repository

   # Clone the repository
   git clone [e-mail]:shipclojure/shipclojure.git
   cd shipclojure
   
   # Set up for future updates
   git remote rename origin upstream
   git remote add origin <your_repository_git_address>

   See Getting Updates for more details on how to manage ShipClojure updates.

Initial Setup

1. Set up the development environment using mise:

   # mise will install the right versions of tools defined in .mise.toml
   mise install

2. Install npm dependencies:

   npm install

3. Set up development secrets:

   cp saas-secrets.example.edn resources/.dev-secrets.edn

   Make sure to update the values in .dev-secrets.edn with your development credentials, especially the database connection. See secrets management for more details.

Development Workflow

ShipClojure offers multiple ways to run the development environment:

Quick Start with Babashka

The easiest way to get started is using Babashka scripts:

# Start both frontend and backend servers
bb dev

This will start the Shadow-CLJS development server (for the frontend) and the Clojure backend server.

NOTE: Changes on the backend server won't be reflected until the server is restarted. See REPL Workflow for a more interactive workflow.

Using the REPL

For a more interactive development experience, check out the REPL Workflow documentation.

Frontend only development

NOTE: This workflow is not recommended. The frontend html is served from a template on the backend, that include only the necessary data and many pages are protected so won't be accessible without the backend running. This is very much a convenience hack and should be used sparingly.

bb frontend-dev

Testing

To run the tests:

# Run Clojure tests
clj -X:test-clj

# Run ClojureScript tests
clj -M:test-cljs

Building for Production

To create a production build:

1. Create .prod-secrets.edn:

cp saas-secrets.example.edn resources/.prod-secrets.edn

1. Update secret values to production ones

2. Run bb release

bb release

This will build optimized frontend assets and prepare the application for deployment.

Next Steps

• Explore the documentation to learn more about the architecture and components
• Check out the UI Components to understand the available UI building blocks
• Learn about the authentication system