Use useMutation() for type-safe mutations with loading states:

`tsx
import { useMutation } from 'convex-solidjs'
import { api } from '../convex/_generated/api'

function MessageForm() {
const [text, setText] = createSignal('')
const sendMessage = useMutation(api.messages.send)

const handleSubmit = async (e: Event) => {
e.preventDefault()

try {
await sendMessage.mutate({
text: text(),
channel: 'general',
})
setText('')
} catch (error) {
console.error('Failed to send:', error)
}
}

return (


Use useAction() for Convex actions (same API as mutations):

`tsx
const generateResponse = useAction(api.ai.generate)

const handleGenerate = async () => {
const response = await generateResponse.mutate({
prompt: 'Hello, AI!',
})
console.log(response)
}
`

API Reference

$3

Creates a Convex client instance.

`tsx
const client = setupConvex('https://your-app.convex.cloud', {
// Optional: disable in SSR
disabled: isServer,
})
`

$3

Subscribe to a Convex query with reactive arguments.

`tsx
const query = useQuery(
api.messages.list,
() => ({ channel: currentChannel() }), // Can be a function or static value
{
enabled: isLoggedIn(), // Conditional fetching
keepPreviousData: true, // Show stale data while loading
initialData: [], // SSR/Hydration support
},
)

// Returns:
query.data() // T | undefined
query.error() // Error | undefined
query.isLoading() // boolean
query.isStale() // boolean
query.refetch() // () => void
`

$3

Execute Convex mutations with loading states.

`tsx
const mutation = useMutation(api.messages.send)

// Call it
await mutation.mutate({ text: 'Hello' })
// or
await mutation.mutateAsync({ text: 'Hello' })

// State
mutation.data() // Result of last successful mutation
mutation.error() // Error from last failed mutation
mutation.isLoading() // Is mutation in progress
mutation.reset() // Clear data and error
`

$3

Execute Convex actions (same API as mutations).

`tsx
const action = useAction(api.ai.generate)
await action.mutate({ prompt: '...' })
`

$3

Get the raw Convex client for advanced use cases:

`tsx
const client = useConvexClient()

// Set auth
await client.setAuth(token)

// Call functions directly
const result = await client.mutation(api.foo.bar, args)
`

Key Design Decisions

1. Reactive Arguments: Both args and options can be static values or accessor functions
2. Resource-Based: Uses SolidJS's createResource for optimal performance
3. Type Safety: Full TypeScript inference with zero type assertions
4. Clean Returns: No property getters, just simple accessor functions

Advanced Usage

$3

Control when queries run with the enabled option:

`tsx
const user = useQuery(
api.users.current,
{},
() => ({ enabled: isAuthenticated() }) // Only fetch when authenticated
)
`

$3

Support server-side rendering with initial data:

`tsx
const messages = useQuery(
api.messages.list,
{ channel: 'general' },
{
initialData: serverData, // Data from SSR
keepPreviousData: true
}
)
`

$3

Access the Convex client directly for advanced scenarios:

`tsx
import { useConvexClient } from 'convex-solidjs'

function AuthButton() {
const client = useConvexClient()

const handleLogin = async () => {
await client.setAuth(token)
}

return Login
}
`

Differences from Other Frameworks

$3

Check out the /dev folder for a complete chat application showcasing:
- User and channel creation
- Real-time message updates
- AI response generation with GPT-4
- Optimistic updates
- Error handling
- Loading states

Run the demo:

`bash
cd dev
pnpm install
pnpm run dev
`

Deploying

In production build pipelines use the build command:

`bash
npx convex deploy --cmd-url-env-var-name VITE_CONVEX_URL --cmd 'npm run build'
`

to build your SolidJS app and deploy Convex functions.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

$3

1. Clone the repository
2. Install dependencies: pnpm install
3. Build the library: pnpm run build
4. Run tests: pnpm test (if applicable)
5. Run the demo: cd dev && pnpm run dev

$3

`
convex-solidjs/
├── src/
│ └── index.tsx # Main library code
├── dev/ # Demo application
│ ├── convex/ # Convex backend
│ └── App.tsx # Demo UI
├── package.json
└── README.md
``

Support

- Documentation
- Discord Community
- GitHub Issues

License

MIT © Frank

---

Built with ❤️ for the SolidJS and Convex communities