README.md

Swift for Raycast Extensions

This Swift Package contains code generation macros and plugins to build a communication channel between Raycast's React extensions and Swift native code. Basically, it lets you import Swift code into your Raycast extension in order to:

• leverage native macOS APIs that might not be exposed to TS/JS, or
• use Swift for targeted sections of your extension, letting you use all Swift language features (such as result builders, async/await, generics/existentials, etc.), or
• compartmentalize your extension into client-facing code (react) and system code (swift).

Requirements

• Xcode.

  Xcode needs to be installed in your system. We are hoping to stop requiring Xcode in the future and just require the existence of a Swift toolchain, alas we are not there yet. Please notice, you don't need to write the swift code in Xcode, you can use any other editor such as VSCode, Sublime, or Nova.

Using the Package

We built a sample extension using Swift here. Check it out to quickly get a feeling how things should be laid out.

To use Swift within Raycast:

1. Create (or fork) a Raycast extension.

   If you don't know how, check out this guide.

2. Create a Swift executable target in the folder of your Raycast extension.

   You can create the target in any of the following ways:

   using Xcode, or

   • Open Xcode
   • File > New > Package... to create a new Swift package
   • Select Executable
   • Select the place within the Raycast extension package you want
   • Untick the "Create Git repository on my Mac"

     I like to put it in a swift folder next to the existing src folder.

   • Delete the main.swift file autogenerated by Xcode.

     This file is reserved for the Raycast plugins generating the TypeScript interface.

   

   using the swift package command in the terminal or VSCode.

   • Run swift package init --type executable --name CustomName in the Raycast extension folder.

     In the previous command, CustomName references the name of the Swift Package. You can name this whatever you want.

   • Delete the main.swift file autogenerated by swift package.

     This file is reserved for the Raycast plugins generating the TypeScript interface.

   You shouldn't have a main.swift file in your project nor a structure marked with @main. These are reserved for the Swift-to-TypeScript plugins.

3. Modify the Package.swift file to include the necessary macros and build plugins.

   // swift-tools-version: 5.9
   
   import PackageDescription
   
   let package = Package(
       name: "CustomName",
   +    platforms: [
   +      .macOS(.v12)
   +    ],
   +    dependencies: [
   +      .package(url: "https://github.com/raycast/extensions-swift-tools", from: "1.0.4")
   +    ],
       targets: [
         .executableTarget(
           name: "CustomName",
   +       dependencies: [
   +         .product(name: "RaycastSwiftMacros", package: "extensions-swift-tools"),
   +         .product(name: "RaycastSwiftPlugin", package: "extensions-swift-tools"),
   +         .product(name: "RaycastTypeScriptPlugin", package: "extensions-swift-tools"),
   +       ]
         ),
       ]
   )

4. Import RaycastSwiftMacros in your Swift file.

   import RaycastSwiftMacros

5. Write global Swift functions and mark them with the @raycast attribute.

   Global functions marked with @raycast are exported to TypeScript. These functions can have any number of parameters, and one or no return type. Exported functions can also be asynchronous (async) or throw errors (throws). The only restrictions are:

   • Parameters must conform to Decodable.
   • The return type (if any) must conform to Encodable (or be Void or ()).
   • Variadic parameters and parameter packs are not supported.
   • Only global functions will be exported. Methods or functions within structs, classes, or enums won't be exported.

   @raycast func greet(name: String, isFormal: Bool) -> String {
    let address = isFormal ? "Mr/Ms" : ""
    return "Hello \(address) \(name)! How are you?"
   }

   Custom types can be received as parameters or returned by the function. You just need to be sure the type conforms to Decodable (for arguments) and Encodable (for return types).

   @raycast func pickColor(name: String) throws -> Color {
     switch name {
     case "red": Color(red: 1, green: 0, blue: 0)
     case "green": Color(red: 0, green: 1, blue: 0)
     case "blue": Color(red: 0, green: 0, blue: 1)
     default: throw Color.Error.unsupportedColor
     }
   }
   
   struct Color: Encodable {
     let red: Float
     let green: Float
     let blue: Float
   
     enum Error: Swift.Error {
       case unsupportedColor
     }
   }