Raycast Scaffold CLI

Raycast is an incredible software for Mac find out more here

They have a great way of building extensions to further extend their software but it involves having to write a lot of files and boilerplate code.

What if there was a simpler way?

This is why I built this simple npx command called Raycast Scaffold, it allows you to write out your basic extension in a YAML file!

Getting started

To get started you need to create a new Raycast Extension using either their CLI or via their launcher.

Then the next step is to open up a new terminal in that folder and run the following command:

npx raycast-scaffold@latest init .

This will then create a new file called extension.yml in the root directory, this is where you'll be crafting your extension.

Here is an example of what the YAML file might look like:

name: test
types:
	project:
		type: local
		title: name
		properties:
			id:
				type: string
				hidden: true
    		name:
				type: string
    		description:
				type: string

As you can see there is a types array, think of types as models or classes, so for example if you're wanting to create an extension for a basic todo tracker then you'll have likely have two types:

• List
• Todo

Each type will have the type property which tells the script where to retrieve and update the data from, this can be set to the following option(s):

"local"

This means it'll be using Raycast's LocalStorage system to store this type locally on your machine.

"api"

This is coming soon but will eventually allow you to use API CRUD endpoints.

You'll also need to specify the title property which should be mapped to the name of one of the properties, this is used when generating the list in the Raycast extension and will be used to display the type's property value.

You can also optionally add the subtitle property which should be mapped to the name of one of the properties, this is used when generating the list in the Raycast extension and will be used as the subtitle of the list itam and display the type's property value.

Then you can add the properties key with a value of object, this is where you assign all the properties for the type.

Here's an example:

properties:
    id:
		type: string
    name:
		type: string
    description:
		type: string

This tells the script you want to use id, name and description for your type.

You can also add in hidden: true for each property if you don't want it visible when using the Create New type commands

Relationships

You can also use relationships, here's an example:

types:
app:
	type: local
	title: name
	properties:
	id:
		type: string
		hidden: true
	name:
		type: string
project:
	type: local
	title: name
	subtitle: appID
	properties:
	id:
		type: string
		hidden: true
	appID:
		type: app
		title: Select App
		display: name
		value: id
	name:
		type: string

See the property appID, I have the type set to app, which tells the script I'm referencing the app type, then I have the title, this is what is displayed for the dropdown in the create new type form.

Then finally there's the display and value properties, the value is set to the property name "id" of the app type which is used as the value to be stored in the project type, the display property is what is shown in the dropdown as a visual cue for the end user to choose between the options, in this example it's set to the property name "name" of the app type.

How to build

To generate all the files for your extension after you've crafted the YAML file, you need to run the following command in the root directory of the extension:

npx raycast-scaffold@latest build . 

This will then build the extension files for you including the A.I tools as well!

Then the last step is to run the following command for Raycast to compile and then start running the extension locally on your machine:

npm run dev