Spreadsheet Architect for Ruby exports

Spreadsheet Architect's Ruby export boundary

Spreadsheet Architect is aimed at developers who need to generate spreadsheet files as application output. Its documented inputs are deliberately narrow and practical: an array containing headers and rows, an ActiveRecord relation, or an array of plain Ruby objects. Its outputs are XLSX, ODS, and CSV, so the same application data can be offered in several common download formats without implementing a separate conversion layer for each one.

The library has two distinct usage models. The first accepts a prepared `data` array and `headers`. This is described by the README as the simplest and preferred approach, particularly when exports become large enough that data-generation performance matters. The second models spreadsheet structure around a Ruby class, usually an ActiveRecord model, through an instance method named `spreadsheet_columns` or a proc supplied in the `:spreadsheet_columns` option.

This makes Spreadsheet Architect more suitable for application exports than interactive workbook design. It documents cell formatting, multiple sheets, defaults, and Rails renderer integration, but it does not present itself as a general-purpose interface for formulas, charts, pivot tables, or workbook editing. Those features may belong to the underlying spreadsheet libraries or may be outside this project's documented contract. The README is silent on them, so Spreadsheet Architect should not be selected on the assumption that it supports them.

Array data and model column mapping

The direct tabular API gives the caller complete control over the data passed to the writer. Headers and rows are supplied separately, and each output format receives the same structures. This path avoids coupling export behavior to a model, which is useful when the rows are assembled from several services or when existing query logic already produces exactly the required values.

The model path uses `spreadsheet_columns` as the default column-definition method. Each definition can contain a header, a method symbol, and an optional cell type. A bare symbol can become both the method used to read a value and the generated header. An ActiveRecord model without a defined `spreadsheet_columns` method falls back to its `column_names` method. This fallback makes a basic model export concise, but it can expose database fields that should not appear in a download. A custom `spreadsheet_columns` method gives the application an explicit place to omit sensitive columns and format values.

For objects that should not define that method, the README shows a proc that receives each instance. This keeps row mapping at the call site and allows computed values, such as a URL classified as a hyperlink or a tag list joined into one cell. The column-definition proc and direct `data` option are different levels of abstraction. Direct data lets the caller shape the entire row set first, while a proc lets the library iterate supplied instances.

Installing Spreadsheet Architect in a Ruby application

The README identifies installation through RubyGems and shows the gem declaration used in a Ruby application. It does not publish a separate operating-system package or container workflow in the documented installation section.

Add the dependency to the Gemfile:

gem 'spreadsheet_architect'

For a first real export, define headers and rows and request XLSX output. The library returns spreadsheet data, so this example writes the result to a local file rather than depending on a Rails response:

file_data = SpreadsheetArchitect.to_xlsx(headers: headers, data: data)

File.open('path/to/file.xlsx', 'w+b') do |f|
  f.write file_data
end

Before this write, the README defines `headers` as `['Col 1','Col 2','Col 3']` and `data` as three rows containing the integers 1 through 9. The expected result is `path/to/file.xlsx` containing that three-column data. The README also shows `SpreadsheetArchitect.to_ods` and `SpreadsheetArchitect.to_csv` with the same inputs when those formats are required.

ActiveRecord relations and plain Ruby instances

To use relation and instance conveniences, include `SpreadsheetArchitect` in the class that defines the export columns. For an ActiveRecord model, the module then supplies `to_xlsx`, `to_ods`, `to_csv`, `to_axlsx_package`, and `to_rodf_spreadsheet`.

Include the module and define an explicit column map:

class Post < ApplicationRecord
  include SpreadsheetArchitect
end

The documented `spreadsheet_columns` format can contain a header, a value or method symbol, and an optional cell type. A symbol such as `:published_at` can use the method name as its header, while `:float` marks a numeric cell. A relation can then call the format-specific method directly. For plain Ruby instances, pass them with the `:instances` option.

The automatic fallback to `column_names` is convenient, but it can include fields the application never intended to publish. Explicit definitions also support calculated cells and optional types such as `:float`. A project with different mapping conventions can name another method with `:spreadsheet_columns` or pass a lambda, avoiding a permanent `spreadsheet_columns` method on the model.

Rails renderers for download responses

Spreadsheet Architect integrates with Rails through format renderers for XLSX, ODS, and CSV. This removes the need for each controller action to repeat the same file-writing pattern. A basic `respond_to` block can render an HTML view or export the selected model format.

A controller can expose all three formats like this:

class PostsController < ActionController::Base
  respond_to :html, :xlsx, :ods, :csv

  def index
    @posts = Post.order(published_at: :asc)

    respond_to do |format|
      format.html
      format.xlsx { render xlsx: @posts }
      format.ods { render ods: @posts }
      format.csv{ render csv: @posts }
    end
  end
end

The renderer examples also accept export options, including `headers: false`, `filename`, and styles. For example, an action can generate the bytes itself, pass a filename, and then render the CSV format. This is useful when exports require different headers or formatting by channel.

The integration depends on Rails conventions and the controller's selected `request.format`. The README does not document authentication checks, streaming behavior, export timeouts, or browser compatibility for generated files. Those concerns must be evaluated in the surrounding application rather than inferred from the renderer examples.

Multi-sheet generation and composition limits

Spreadsheet Architect supports workbook composition for XLSX and ODS. The documented pattern creates an initial package or spreadsheet from one sheet's headers and data, passes that object as an additional argument when creating the next sheet, and writes the accumulated result to disk.

For XLSX, create the package first and add the second sheet:

axlsx_package = SpreadsheetArchitect.to_axlsx_package({headers: sheet_1_headers, data: sheet_1_data})
axlsx_package = SpreadsheetArchitect.to_axlsx_package({headers: sheet_2_headers, data: sheet_2_data}, axlsx_package)

File.open('path/to/multi_sheet_file.xlsx', 'w+b') do |f|
  f.write axlsx_package.to_stream.read
end

The ODS section uses the same accumulation idea with `SpreadsheetArchitect.to_rodf_spreadsheet`. This is workbook assembly at the Spreadsheet Architect API level, not a high-level sheet registry. Callers must retain and pass the package or spreadsheet object correctly.

The README excerpt does not document cross-sheet formulas, references between sheets, charts, images, merged-cell policies, or workbook-level metadata. It also does not show CSV multi-sheet behavior because CSV has no native multi-sheet structure. Projects whose requirements extend beyond composing data sheets should inspect the capabilities of the underlying `axlsx` and `rodf` objects directly.

Maintenance, licensing, and upgrade boundaries

The repository is not archived, and its last push was on 2026-08-04. Recent releases listed for the project include `v5.1.1` on 2026-04-27, `v5.1.0` on 2025-01-07, and `v5.0.1` on 2024-07-23. Those dates indicate recent repository activity, but they do not establish compatibility with every Ruby, Rails, or spreadsheet dependency combination. The visible repository includes a `CHANGELOG.md`, Gemfile, gemspec, tests, and a GitHub Actions workflow, which gives an adopter places to inspect changes and dependency declarations.

The project uses the MIT License. That designation permits use, modification, distribution, and sublicensing subject to the license text and its notice requirements. This review does not interpret whether a particular commercial deployment complies with those obligations. An adopting organization should review the repository's `LICENSE` file itself.

Upgrade planning should focus on the major-version boundary from the listed `5.0.x` and `5.1.x` releases. The README does not provide a version-compatibility matrix, supported Ruby versions, or an explicit upgrade procedure. The changelog and tests are therefore the concrete files to inspect before changing the locked gem version.

Choosing direct rows instead of relation exports

The direct `headers` and `data` API is the better fit when export rows come from services, joined queries, calculated values, or application-specific batching. It also gives developers a clear place to decide column order and cell contents. The README specifically recommends creating the data array yourself when generation performance matters, although it does not quantify memory consumption or show a streaming API.

The relation API is more convenient for conventional ActiveRecord exports. It accepts a query relation and uses the model's column configuration. That convenience introduces a coupling: changes to `spreadsheet_columns`, associations used inside the mapping, or database columns can alter a download. It also means the model must include `SpreadsheetArchitect`, which should be an intentional design choice rather than a requirement imposed on every plain Ruby class.

A real alternative is to build headers and rows in application code, then call `SpreadsheetArchitect.to_xlsx`, `to_ods`, or `to_csv`. Another approach would be to write each spreadsheet format through its underlying library directly, accepting less shared application logic in exchange for direct access to format-specific features. Spreadsheet Architect is a good fit when one column model and several output formats matter more than workbook-specific functionality.

Editorial conclusion

Ruby and Rails applications that need model-driven spreadsheet exports should adopt Spreadsheet Architect when its column-definition and Rails integration model match their needs. Projects that require undocumented workbook features should first inspect the underlying spreadsheet libraries and avoid treating this package as a full workbook editor. For large datasets, verify that manually generated tabular data fits the application's memory budget before using the ActiveRecord convenience path.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. westonganger/spreadsheet_architect on GitHub