Skip to main content

Best Practices for Developers

Guidelines for SPECS developers: sample projects, project structure, script conventions, AI context, Git setup, credentials, team workflows, and video tutorials.

These guidelines are for anyone building a Lens for SPECS in Lens Studio, alone or in a team. They cover where to start (sample projects and the specs-devs resources), how to lay out a project and write its scripts, how to set up Git and keep credentials out of it, and how a team can share one scene without losing work. Each section stands on its own, so jump to the one you need.

Start a SPECS project from a sample project

Starting your SPECS development with a sample project is the recommended path. The SPECS sample projects show what the APIs and the platform can do, with working examples of the practices on this page.

You can get the sample projects in two places:

What the specs-devs GitHub organization contains

The specs-devs GitHub organization has three repositories of resources for SPECS developers:

RepositoryWhat it holdsUse it to
samplesComplete Lens Studio projects, each showing a specific API or platform feature. You can learn from them and build on them.Start a project, or see a feature working. The Samples page lists them all.
packagesThe unpacked versions of packages you usually install from the Asset Library.Read a package's source. Keep the copy in your project packed (see Keep Asset Library packages packed).
contextA filtered, lightweight set of resources curated for AI context engineering, including example rule files.Give an AI coding assistant SPECS context (see Give an AI coding assistant SPECS context).

Keep Asset Library packages packed

Keep the packages you install from the Asset Library packed, and keep them up to date. Once you unpack a package, you can no longer pull its updates from the Asset Library. Unpack a package only when you must change one of its internal components. The unpacked source of the SPECS packages is in the specs-devs/packages repository if you only need to read it.

If you must change a component of an unpacked package:

  1. Duplicate the component's file, and leave the original unchanged.
  2. Add a _Modified suffix to the copy's file name, for example Interactable_Modified.ts.
  3. Update your imports to reference the modified copy.
  4. Mark the package folder as modified, so collaborators know it no longer matches the Asset Library version.

Give an AI coding assistant SPECS context

The specs-devs/context repository is a filtered, lightweight collection of resources curated for AI context engineering. When you put it in the same workspace as your Lens Studio project, in an AI code editor such as Cursor, the editor indexes it and your AI coding assistant can use it. Reference those files when you ask your assistant questions about SPECS development.

Rules are system prompts that you set in your editor to guide the assistant's behavior. In Cursor, for example, rules are files in a .cursor/rules/ folder in your workspace (see Rules in the Cursor documentation for the file format). The context repository has example rule files you can adapt for SPECS development, in its rules/ folder.

For what context Lens Studio already gives an assistant, and how to add your own, see Give Your AI Agent Lens Studio Context.

Organize the Assets folder of a SPECS project

These guidelines keep a Lens Studio project clean, organized, and maintainable. Keep your own work in a Project/ folder inside the project's Assets/ folder:

Assets/
├── Project/ # Your main contribution folder
│ ├── Scripts/ # TypeScript and JavaScript source files
│ ├── Materials/ # Custom materials
│ ├── Shaders/ # Custom shader code
│ ├── Textures/ # Texture files
│ ├── Images/ # Image assets
│ ├── Prefabs/ # Reusable scene objects
│ ├── Animations/ # Animation files
│ ├── Sound/ # Audio files
│ └── Data/ # JSON configs and data files
├── Render/ # Rendering-related components
│ ├── CameraTexture/
│ ├── EnvironmentMaps/
│ └── [camera layer configs]
└── Examples/ # Standout examples (optional)

Three kinds of content get folders of their own, outside Assets/Project/:

  • Render/: keep every rendering component together, such as camera textures and environment maps, along with anything that deals with camera layers and rendering. This keeps rendering concerns separate from the Lens's logic.
  • Examples/: use it when you want users of your project to discover something right away. It suits standout examples that show off key features.
  • Imported assets: give a complex import, such as a Sketchfab model with many dependencies, its own folder with all its related files. An import that bundles its own animations, textures, and other content can live on its own like this.

Name scripts in a project with both TypeScript and JavaScript

If your project's code exists in both TypeScript and JavaScript, add a TS or JS suffix to each script's file name:

Scripts/
├── MyComponentTS.ts # TypeScript version
├── MyComponentJS.js # JavaScript version
├── HelperTS.ts # TypeScript helper
└── HelperJS.js # JavaScript helper

The suffix shows at a glance which language version you're working with, and prevents confusion when both versions of a script sit in the same folder.

Comment and document Lens Studio scripts

Write comments as single-line comments, for consistency. When a comment needs more explanation, use several single-line comments:

// Keep comments as one-liners for consistency
// If you need more explanation, use multiple single-line comments

Start each script component with a documentation comment that says what the component does, which other components it's connected to, and what it does at each stage of its lifecycle:

/**
* PlayerController
*
* Manages player movement and interaction with the game world.
* Connected to: GameManager, InputHandler, PhysicsSystem
*
* Lifecycle: initializes in onAwake, starts tracking in OnStartEvent
*/
@component
export class PlayerController extends BaseScriptComponent {
// Class implementation
}

Give script variables descriptive names and types

In a Lens Studio script, give each variable a name that says what it's for, and a type: a type annotation in TypeScript, a JSDoc @type comment in JavaScript.

@component
export class VariableHints extends BaseScriptComponent {
// Good: clear intent and type
private movementSpeed: number = 5.0;
private targetPosition: vec3 = vec3.zero();
private isInteracting: boolean = false;

// Bad: unclear purpose
private speed = 5.0;
private pos = vec3.zero();
private flag = false;
}

Set up every lifecycle event in a script component

Always set up a script component's lifecycle events, onAwake, OnStartEvent, and UpdateEvent, even when one of them is empty. This sample also logs each stage when its Enable Logs input is on:

@component
export class MyComponent extends BaseScriptComponent {
@input
enableLogs: boolean = true;

onAwake() {
if (this.enableLogs) {
print('[MyComponent] onAwake called');
}
// Initialization logic

this.createEvent('OnStartEvent').bind(() => {
if (this.enableLogs) {
print('[MyComponent] OnStartEvent triggered');
}
// Start logic
});

this.createEvent('UpdateEvent').bind(() => {
// Update logic (can stay empty)
});
}
}

Handle missing inputs and control logging in a script component

Check an input that may be left empty

Lens Studio checks every TypeScript @input for undefined: if an input isn't set in the Inspector, the Lens throws a run-time error. To let an input stay empty and handle that case yourself, add @allowUndefined to it (see AllowUndefined in the TypeScript page), then check the input and print a clear error message when it's missing:

@component
export class TargetCheck extends BaseScriptComponent {
@input
@allowUndefined
targetObject: SceneObject;

onAwake() {
if (!this.targetObject) {
print('[ERROR] TargetCheck: targetObject is not assigned');
return;
}
// Proceed with logic
}
}

Turn logging on and off with inputs

Give each script component a logging switch, so you can turn its logs on and off from the Inspector. This sample has two inputs: Enable Logs turns all logs on or off, and Verbose Logs adds detailed messages:

@component
export class LoggingComponent extends BaseScriptComponent {
@input
private enableLogs: boolean = true;

@input
private verboseLogs: boolean = false;

private log(message: string, verbose: boolean = false) {
if (!this.enableLogs) return;
if (verbose && !this.verboseLogs) return;
print(`[LoggingComponent] ${message}`);
}

onAwake() {
this.log('Component initialized');
this.log('Detailed initialization info', true); // Verbose log
}
}

Use const and let, and format your code

In Lens Studio scripts, in TypeScript and in JavaScript, declare variables with const or let, not var:

// Good
const maxHealth = 100;
let currentHealth = 100;

Avoid:

var maxHealth = 100;

Format your scripts with a code formatter such as Prettier. A formatter keeps spacing and syntax consistent across the project, which makes collaboration easier.

Teach users how to use your SPECS Lens

Show users, inside the Lens, how to use it:

  • Add text instructions. Include UI text that explains how to use the Lens: its gestures, interactions, and features. Keep the instructions clear and concise.
  • Add 3D hand hints. Use the 3D Hand Hints package to show users which hand gestures the Lens needs, and to display hints for specific interaction patterns. Hand hints are essential for a Lens with custom gestures.

Use UI Kit and Interaction Kit components instead of custom ones

For SPECS UI and interactions, prefer the framework components to your own:

  • Use UI Kit components for UI elements.
  • Use Interaction Kit components for interactions.
  • Follow each framework's own best practices.

Import the framework components from their packages. Use a custom implementation, such as a modified copy of a component, only when you need one:

// Good: use framework components
import { RectangleButton } from 'UIKit.lspkg/Scripts/Components/Button/RectangleButton';
import { Interactable } from 'InteractionKit.lspkg/Components/Interaction/Interactable/Interactable';

// Only if necessary: custom implementations
import { CustomButton } from './CustomButton_Modified';

Document a SPECS project repository

Write a README

Give your project repository a README that covers what the Lens does, its features, how to use it, its technical details, a demo, and credits:

# Project Name

Brief description of what your Lens does.

## Features

- Feature 1
- Feature 2

## How to Use

Step-by-step instructions with screenshots or GIFs.

## Technical Details

- Framework dependencies
- API requirements
- Performance considerations

## Demo

![Demo](docs/demo.gif)

## Credits

List any third-party assets or code used.

Add animated GIFs and technical explanations to make the README engaging and informative.

Credit sources in a LICENSE file

Always credit the sources of third-party assets and code, in the repository's LICENSE file:

This project includes assets from:
- [Asset Name] by [Author] - [License Type]
- [Model Name] from Sketchfab by [Creator]

Set up .gitignore and .gitattributes for a Lens Studio project

Lens Studio writes and maintains a .gitignore and a .gitattributes file for you when you save a project inside a Git repository. Use those files rather than writing your own from scratch:

  1. In a terminal, go to your project folder and run git init.
  2. Save the project in Lens Studio. Lens Studio adds .gitignore and .gitattributes to the folder, or updates them.
  3. Make your first commit, including both files.

Each generated file has a section that Lens Studio manages, between # Shipped by Lens Studio markers. Don't edit that section: Lens Studio overwrites it every time it saves. Put your own entries above or below it. The managed section of .gitignore ignores these:

Cache/**
PluginsUserPreferences/**
Support/**
BackUp/**
Workspaces/**
.vscode/**
/jsconfig.json
/tsconfig.json
.DS_Store
/spk_debug_key.pem
*.lock

It doesn't ignore the Packages/ folder or .lsc files, and you shouldn't either: Packages/ holds the project's installed packages (.lspkg) and custom components (.lsc), so a collaborator who clones a repository without them gets a project with missing dependencies. Don't commit spk_debug_key.pem: the managed section already excludes it.

Add your own entries outside the managed section, for example operating system and editor files the managed section doesn't cover, and your credential files (see Keep credentials out of a SPECS project repository):

# Your own entries, above or below the Lens Studio section
Thumbs.db
.idea/

The generated .gitattributes stores everything under Assets/ and Packages/ in Git LFS, and marks text files such as .js, .json, and .md as text eol=lf so their line endings stay consistent. Keep it, rather than replacing it with your own line-ending rules: a rule such as * text=auto drops Git LFS for the project's binary assets. Every collaborator needs Git LFS installed (git lfs install), or Lens Studio can't open the cloned project. For more on Git and Lens Studio projects, see Lens Studio Project Structure.

Keep credentials out of a SPECS project repository

Protecting sensitive information in a Lens Studio project is critical. Never commit tokens, API keys, passwords, or other credentials to a Git repository. Protect these:

  • API tokens and keys
  • Service account credentials
  • Database passwords
  • OAuth secrets
  • Private encryption keys

Snap Cloud credentials

When you work with Snap Cloud, Import Credentials in the Supabase panel (Window › Supabase) creates a Supabase Project asset in your project, Assets/SupabaseProject_<ref>.supabaseProject, which holds your Snap Cloud project's URL and public token. Don't push this asset to Git: add it to your .gitignore, outside the Lens Studio section:

# Snap Cloud project credentials
*.supabaseProject

Each collaborator then imports the credentials into their own copy of the project. See Lens Setup Guide.

Remote Service Gateway tokens

The Remote Service Gateway uses Snap, OpenAI, and Google tokens tied to your Snapchat account, which you generate with the Remote Service Gateway Token plugin and enter in the RemoteServiceGatewayCredentials component. Don't commit a scene where those tokens are visible in the Inspector:

  1. Clear the token fields of the RemoteServiceGatewayCredentials component.
  2. Commit your changes.
  3. Enter the tokens again locally, for testing.

Alternatively, store the tokens in a separate configuration file that .gitignore excludes, and load them at run time instead of saving them in the scene. See Remote Service Gateway.

Keep server-side keys in Edge Function secrets

Keep server-side keys in Snap Cloud Edge Function secrets, not in the Lens: you set them with supabase secrets set, and the Edge Function reads them as environment variables (see Edge Functions). Share any other credentials only through private channels:

  • Share credentials only through secure channels, such as encrypted messages and password managers.
  • Never share credentials in public forums, Discord, or GitHub issues.
  • Rotate a credential immediately if it's accidentally exposed.

Separate development and production configuration files

Create separate configuration files for development and production, and commit only a template without real values:

Assets/
├── Config/
│ ├── development.json # Local dev credentials (gitignored)
│ ├── production.json # Prod credentials (gitignored)
│ └── config.template.json # Template without actual values (committed)

Share a Lens Studio scene in a team with a Scene Master

Lens Studio's project format is designed to keep Git merge conflicts to a minimum, and the Git merge tools Lens Studio sets up reduce them to the essential ones: two people can change different properties of the same object in parallel. A conflict still happens when two people change the same property, or reorder the same part of the scene hierarchy, and scene files are where the whole team's work meets, so their conflicts are the hardest to merge. To avoid them, designate a Scene Master:

  • One team member is responsible for the final changes to the scene.
  • The other team members work on prefabs and assets.
  • The Scene Master integrates the prefabs into the main scene.

For example:

Team Member A → Works on UI prefabs
Team Member B → Works on game logic scripts
Team Member C → Works on visual assets
Scene Master → Integrates all prefabs into main scene

Build the Lens from prefabs

Keep each team member's work modular and reusable by building it as prefabs:

Assets/
├── Project/
│ ├── Prefabs/
│ │ ├── UI/ # UI components by Team Member A
│ │ ├── Gameplay/ # Game objects by Team Member B
│ │ └── Effects/ # VFX by Team Member C
│ └── Scripts/ # Scripts by all team members

Prefab-driven development has these benefits:

  • Team members can work on their prefabs independently.
  • Prefabs are easier to merge than scene files.
  • Changes stay isolated and testable.
  • The Scene Master can integrate prefabs without conflicts.

Give each team member a folder

Give each team member's work its own folder in the Assets/Project/ folder:

Assets/
├── Project/
│ ├── TeamMemberA/ # Alice's workspace
│ ├── TeamMemberB/ # Bob's workspace
│ ├── Shared/ # Shared resources
│ └── Integration/ # Scene Master's integration work

This structure minimizes conflicts and makes it clear who owns what.

Commit only the files you changed in a Lens Studio project

Don't stage everything with git add . (add all):

git add .
git commit -m "Updated stuff"

Review your changes and stage the files you edited by name instead:

# Review what changed
git status

# Add specific files you edited
git add Assets/Project/Scripts/PlayerController.ts
git add Assets/Project/Prefabs/UI/MainMenu.prefab

# Verify what's staged
git diff --staged

# Commit with a clear message
git commit -m "Add player movement controls to PlayerController"

Selective commits matter because they:

  • Prevent you from committing credentials by accident.
  • Keep temporary files and test assets out of the repository.
  • Keep the commit history clean and reviewable.
  • Make it easier to revert a specific change.

Checklist for a SPECS project

Starting a new project

  • Create the Assets/Project/ folder structure.
  • Set up the Render/ folder for rendering components.
  • Add a README.md with a project overview.
  • Commit the .gitignore and .gitattributes that Lens Studio generates, with your credential files added to .gitignore.
  • Set up logging with an on/off input.
  • If you work in a team, designate a Scene Master.

Writing script components

  • Add a class-level documentation comment.
  • Set up every lifecycle event, even if empty.
  • Add logging with an enable/disable input.
  • Handle inputs that may be missing, with error messages.
  • Use const and let instead of var.
  • Give variables types.

Using packages

  • Keep packages packed unless you need to modify them.
  • If you modify a component, duplicate it and add a _Modified suffix.
  • Update imports to point at the modified components.

Security and Git

  • Never commit credentials, tokens, or API keys.
  • Add sensitive files to .gitignore.
  • Remove credentials from the Inspector before you commit.
  • Use git add <file> instead of git add ..
  • Review changes with git status and git diff.

Before publishing

  • Add UI text instructions for users.
  • Include 3D hand hints if the Lens uses custom gestures.
  • Create an animated GIF for the README.
  • Document the technical requirements.
  • Credit all third-party assets in LICENSE.
  • Run a code formatter (Prettier).
  • Verify that no credentials are in the repository.
  • Test all features and interactions.

Video tutorials for SPECS development

These videos are recommended viewing for SPECS development:

#VideoWhat it covers
1Introduction to Lens StudioLens Studio basics and an overview of the interface
2Building Your First LensBuilding a first SPECS Lens
3Connected LensesConnected Lenses on SPECS
4UI Kit WalkthroughA walkthrough of UI Kit
5Snap MLThe SnapML pipeline for SPECS
6Snap CloudGetting started with Snap Cloud

For more tutorials and updates, visit the SPECS developers YouTube channel.