Learn

Recipes

MarkdownEdit on GitHub

Short, complete answers to things most apps need. Each one is a whole program: paste it into src/app.art and run npm run dev. All of them are compiled by the test suite, so they stay correct.

A form with validation #

The server checks every write against the model's rules; the form shows its message.

ArtScript
model Signup {
  id: ID
  name: String min=2 max=40
  email: Email unique
  age: Number min=18
}

api signups: Signup

page Join "/" {
  state name = ""
  state email = ""
  state age = 18
  state problem = ""
  state done = false

  fn submit() {
    try {
      await api.signups.create({ name, email, age })
      done = true
      problem = ""
    } catch (e) {
      problem = e.message
    }
  }

  if done {
    text "Thanks, you're in." success
  } else {
    form gap=3 -> submit() {
      input name label="Name" required
      input email label="Email" type=email required
      input age label="Age" type=number
      if problem != "" {
        text problem danger
      }
      button "Join" primary
    }
  }
}

input age type=number binds a Number. The error message comes from the server (name must have at least 2 characters, email is already used), so the rules live in one place.

Search, sort and pagination #

data re-runs its query when a state it uses changes.

ArtScript
model Product {
  id: ID
  name: String
  price: Number
}

api products: Product

page Products "/" {
  state q = ""
  state sort = "name"
  state page = 0
  data items = api.products.list({ search: q, sort, limit: 10, offset: page * 10 })
  data total = api.products.count({ search: q })
  computed pages = Math.max(1, Math.ceil(total / 10))

  column gap=3 {
    row gap=2 {
      input q placeholder="Search" on:input=(page = 0)
      select sort options=[{ value: "name", label: "Name" }, { value: "-price", label: "Most expensive" }, { value: "price", label: "Cheapest" }]
    }
    table {
      tr {
        th "Name"
        th "Price"
      }
      for p in items key p.id {
        tr {
          td p.name
          td `$${p.price}`
        }
      }
    }
    row gap=2 align=center {
      button "Previous" small disabled=(page == 0) -> page--
      text `Page ${page + 1} of ${pages}` muted
      button "Next" small disabled=(page + 1 >= pages) -> page++
    }
  }
}

Confirm before deleting #

ArtScript
model Note {
  id: ID
  text: String
}

api notes: Note

page Notes "/" {
  data notes = api.notes.list()
  state asking = false
  state target: Note? = null

  fn ask(n) {
    target = n
    asking = true
  }
  fn confirm() {
    if target {
      await api.notes.remove(target.id)
    }
    asking = false
    notify("Deleted", "success")
  }

  column gap=2 {
    for n in notes key n.id {
      row gap=2 {
        text n.text
        button "Delete" small danger -> ask(n)
      }
    }
  }
  modal asking gap=3 {
    title "Delete this note?" small
    text target?.text ?? "" muted
    row gap=2 justify=end {
      button "Cancel" -> asking = false
      button "Delete" danger -> confirm()
    }
  }
}

modal asking opens while asking is true; Esc and the backdrop close it. For a ready-made version, npx art add ConfirmButton.

Upload an image with a preview #

ArtScript
model Profile {
  id: ID
  name: String
  photo: File? max=2000000 accept="image/*"
}

api profiles: Profile

page Profiles "/" {
  data profiles = api.profiles.list()
  state name = ""
  state photo: File? = null
  computed preview = photo ? URL.createObjectURL(photo) : ""

  fn save() {
    await api.profiles.create({ name, photo })
    name = ""
    photo = null
  }

  column gap=3 {
    form gap=2 -> save() {
      input name label="Name"
      file photo accept="image/*" label="Photo"
      if preview != "" {
        image preview width=120 alt="Preview"
      }
      button "Save" primary
    }
    grid cols=2 md:cols=4 gap=3 {
      for p in profiles key p.id {
        card gap=2 {
          if p.photo {
            image p.photo.url alt=p.name
          }
          text p.name bold
        }
      }
    }
  }
}

Remember a setting in the browser #

ArtScript
page Settings "/" {
  state compact = localStorage.getItem("compact") == "yes"

  effect {
    localStorage.setItem("compact", compact ? "yes" : "no")
  }
  checkbox compact label="Compact view"
  text compact ? "Compact" : "Comfortable" muted
}

effect re-runs whenever compact changes. For the theme, setTheme already remembers the choice.

Tabs that live in the URL #

ArtScript
page Account "/account" {
  state tab = query.tab ?? "Profile"

  effect {
    history.replaceState(null, "", `?tab=${tab}`)
  }
  tabs tab options=["Profile", "Billing", "Security"]
  if tab == "Profile" {
    text "Your profile"
  } else if tab == "Billing" {
    text "Your plan and invoices"
  } else {
    text "Password and sessions"
  }
}

Reloading or sharing the link keeps the tab.

Live data: a tiny chat #

ArtScript
model User {
  id: ID
  email: Email unique
  password: String min=8
  name: String
}

api users: User

auth users

model Message {
  id: ID
  author: User
  text: String min=1 max=500
  sent: Number
}

api messages: Message login

page Chat "/" requires login {
  data me = auth.me()
  data messages = api.messages.list({ sort: "sent", limit: 100 }) live
  state draft = ""

  fn send() {
    if me {
      await api.messages.create({ author: me, text: draft, sent: Date.now() })
      draft = ""
    }
  }

  column gap=2 {
    for m in messages key m.id {
      row gap=2 {
        text m.author.name bold
        text m.text
      }
    }
    input draft placeholder="Message" -> send()
  }
}

live reloads the list when anyone writes to it, over a single server-sent events connection.

Call an external API with a secret #

Secrets stay on the server: read them in a server fn from the environment.

ArtScript
server fn weather(city) {
  let key = process.env.WEATHER_KEY ?? ""
  if key == "" {
    fail("WEATHER_KEY is not set", 500)
  }
  let res = await fetch(`https://api.example.com/weather?q=${encodeURIComponent(city)}&key=${key}`)
  if !res.ok {
    fail("The weather service didn't answer", 502)
  }
  let body = await res.json()
  return { city, temp: body.temp }
}

page Weather "/" {
  state city = "Buenos Aires"
  data report = server.weather(city)

  input city placeholder="City"
  if report {
    text `${report.temp}° in ${report.city}`
  } else {
    spinner
  }
}

Send a form by email from a static site #

Without a server (GitHub Pages, any static host), a form service such as Web3Forms or Formspree takes the request and emails it. Its key is public: anyone can read it in the page and send with it, so the page limits what one browser sends, a hidden field catches simple bots, and the service's own limits (and its allowed-domains setting) do the rest.

ArtScript
const FORM = "https://api.web3forms.com/submit"
const KEY = "your-public-access-key"

page Contact "/contact" {
  state email = ""
  state message = ""
  state trap = ""
  state status = ""

  fn send() {
    // At most 3 messages an hour from one browser.
    let sent = JSON.parse(localStorage.getItem("sent") ?? "[]").filter(t => Date.now() - t < 3600000)
    if trap != "" || sent.length >= 3 {
      status = "Please try again later."
      return
    }
    try {
      let res = await fetch(FORM, {
        method: "POST",
        headers: { "content-type": "application/json" },
        body: JSON.stringify({ access_key: KEY, email, message })
      })
      if !res.ok {
        throw new Error(`The form service answered ${res.status}`)
      }
      localStorage.setItem("sent", JSON.stringify([...sent, Date.now()]))
      status = "Thanks, we'll write back soon."
      message = ""
    } catch (e) {
      status = "It didn't go through. Write to hello@example.com."
    }
  }

  style {
    .trap { position: absolute; left: -9999px; }
  }

  form gap=3 -> send() {
    input email label="Email" type=email autocomplete="email" required
    textarea message label="Message" required
    // People don't see this field; bots fill it.
    column class="trap" aria-hidden="true" {
      input trap label="Website" autocomplete="off" tabindex=-1
    }
    if status != "" {
      text status muted
    }
    button "Send" primary
  }
}

test "sends the message" {
  open "/contact"
  respond "https://api.web3forms.com/*" 200 { success: true }
  fill "Email" "ana@example.com"
  fill "Message" "Hi"
  click "Send"
  see "Thanks, we'll write back soon."
}

The test answers for the service with respond, so running it never sends mail. In an app with an api, send from a server fn instead (as in the recipe above): its server only lets the page talk to its own origin.

Animations without code #

Entrances, scroll reveals, hover effects and staggered lists are flags and props on any element: no CSS, no observers, no library. reveal appears when scrolled into view (siblings one after another), animate= plays on mount, stagger delays a container's children, hover= answers the pointer. Reduced-motion settings are respected and a prerendered page shows everything without JavaScript. Backgrounds and counters come as components: art add MeshBackground Particles Marquee Counter.

ArtScript
page Home "/" {
  column gap=8 {
    column class="hero" gap=3 align=center pad=10 {
      title "Nimbus" tag=h1 animate=rise
      text "The simple way to launch." muted animate=rise delay=120
      button "Get started" primary hover=grow animate=pop delay=240
    }
    grid cols=1 md:cols=3 gap=4 stagger {
      card reveal hover=lift {
        text "Fast" bold
        text "Ready in minutes." small
      }
      card reveal hover=lift {
        text "Simple" bold
        text "Nothing to configure." small
      }
      card reveal hover=lift {
        text "Open" bold
        text "Open source, no lock-in." small
      }
    }
  }
}

For a game loop or a physics simulation, write the engine in a .ts file and import it with use: that code is plain TypeScript and costs an agent the same as in any stack.

A chart #

Charting libraries draw into an element: ref hands it over, mount starts the chart and cleanup stops it.

ArtScript
use "chart.js/auto" as Chart

page Sales "/" {
  state values = [12, 19, 7, 15, 22]
  ref canvas

  mount {
    let chart = new Chart(canvas, { type: "bar", data: { labels: values.map((_, i) => `Week ${i + 1}`), datasets: [{ label: "Sales", data: values }] } })
    cleanup {
      chart.destroy()
    }
  }
  column ref=canvas style="max-width: 640px"
}

Install it first: npm install chart.js.

Format dates and money #

Formatters are fns at the top level of a .art file: every component can call them, and the checker verifies them.

ArtScript
fn day(ms) {
  return new Intl.DateTimeFormat("en-US", { dateStyle: "medium" }).format(ms)
}

fn money(n) {
  return new Intl.NumberFormat("en-US", { style: "currency", currency: "USD" }).format(n)
}

page Invoice "/" {
  state issued = Date.now()
  state total = 1234.5

  text `Issued ${day(issued)}` muted
  text money(total) bold large
}

An admin area #

ArtScript
model User {
  id: ID
  email: Email unique
  password: String min=8
  role: String
}

api users: User

auth users

model Post {
  id: ID
  title: String
  published: Bool = false
}

api posts: Post admin

page Blog "/" {
  data posts = api.posts.list({ where: { published: true } })

  for p in posts key p.id {
    text p.title
  }
}

page Admin "/admin" requires admin {
  data posts = api.posts.list()
  state title = ""

  input title placeholder="New post" -> api.posts.create({ title })
  for p in posts key p.id {
    checkbox p.published label=p.title -> api.posts.update(p.id, { published: p.published })
  }
}

The first account is the admin. admin on the api protects the data; requires admin keeps the page from showing to anyone else.

A nightly cleanup #

ArtScript
model Draft {
  id: ID
  text: String
  updated: Number
}

api drafts: Draft

server job cleanup every "1d" {
  let monthAgo = Date.now() - 30 * 24 * 3600 * 1000
  db.drafts.list().filter(d => d.updated < monthAgo).forEach(d => db.drafts.remove(d.id))
}

Jobs don't overlap: if a run takes longer than the interval, the next one waits.